MacFormat 1997 January

home *** CD-ROM | disk | FTP | other *** search

/ MacFormat 1997 January / macformat46.iso / Shareware Plus / Developers / EnterAct / EnterAct Stuff / Documentation / EnterAct 3 Manual < prev next >

Wrap

Text File | 1996-10-08 | 353.9 KB | 9,405 lines

****************ENTERACT™ USER’s MANUAL***************** - - - - - - - - - - - - Preface and Copyright - - - - - - - - - - - - ____ Copyright © 1991-1996 by Dynabyte. EnterAct 3.7, by Ken Earle. All rights reserved. EnterAct's basic text engine is a modified form of Roy Wood's "TE32K" package. You can find it on the net (search for "Roy Wood" or "TE32K"). "More Files" provides some nifty file handling features. "Jims CDEFs" (or "Jim's CDEFs") does the square buttons and tab panels. Thanks to Zelko Jagaric, Wai Choi, Rob Gibson, Steve Olson, Jean François Cassan, Mark Wong, Scott Jenson, Bill Sears, Sandra Lakin, Nicolas Berloquin, Romain Vignes &c for help and constructive abuse. (Using EnterAct? <Option>zoom to open this window up) You can reach me at: Ken Earle 697 Spadina Ave Toronto, ON CANADA M5S 2J1 kearle@interlog.com via Internet (preferred) 73073,2166 via CompuServe (I'll be dropping this) ____ The 68K version of EnterAct 3 is FREE. No catch. There is, as yet, no released native PPC version. "hAWK", "Read Resource", their associated source code and manuals, and the Drag_on Modules interface are yours to keep, free, no matter what. They are governed by the Free Software Foundation's "copyleft", as described in the document "copying hAWK", included with your EnterAct package. You may distribute full copies of EnterAct (omitting no files from the compressed archive that comprises EnterAct), provided you do not charge for EnterAct itself. This includes CD distribution. EnterAct is an editor for creating, maintaining, and reviewing C, C++ and Java code. EnterAct has many capabilities (most notably real-time automatic definition and prototype display, even out of first-draft code) that just aren’t "out there" yet. This is a finite-lived product, intended to fill the gap until EnterAct’s best features are available elsewhere. Let’s hope it doesn’t take more than a year or two. That having been said, please note that EnterAct itself is a solid editor. It’s been around since 1989. If you just want to use EnterAct as a "definition viewer" to help out some other editor, see the section ____ § EnterAct as a "definition finder" ____ (to get there, use "Enter Selection" and "Find Again" on the above line). Metrowerks codewarriors, please see Appendix 5. Symantec lightspeeders, please see Appendix 4. (Using EnterAct? <Option> click in the title bar here) MPWers, start doing your happy dance. For the very very impatient: •1 Start up EnterAct ( if you haven't yet). •2 Make a project (New Project), just as with THINK C etc. Select your preferred folder for <header> files in the next dialog that appears, or Cancel to use the folder that contains EnterAct. •3 Drag files or folders onto the project window to add files. •4 "Update Dictionary". See "DON’T GIVE UP" a page or so below if you run into a problem. Usually problems are rare, fixes are easy. •5 Pick the "AutoLook" command (it explains itself). •6 Open a project source file and browse around. Double-click on or click just after any name that you’d like to see a definition or prototype for. Watch the AutoLook window. Press <Enter>. •7 Come on back here, and learn about all the other good stuff (persistent lookup windows, cross-referencing, Automark, browser, hyperlinks, the hAWK language, code templates, persistent undo, etc). For the just very impatient: see "EnterAct in brief" instead of this. Included there are details on using EnterAct as a "definition viewer" while working with other editors. - - - - - - - - - - - - Requirements - - - - - - - - - - - - (§) Network and team users please read this EnterAct does not keep files open, except when in the act of reading and writing them. EnterAct is, however, SourceServer aware, and won't allow changes to a file that have been checked out as read-only unless you issue a "Modify Read Only" command or enable EnterAct's "ignore ckid's" option. So use (multiple copies of) EnterAct only if you have some way of ensuring that you won't have several people working on the same copy of a file at the same time (such as SourceServer/Projector). (§) System requirements System 7 required. Mac II speed (!! that is, a 68020 running at 16 mHz) is recommended if your project contains more than about 500K of text in source and header files combined. A hard disk is a practical necessity. A large screen (>= 16 inches) will allow you to take better advantage of EnterAct’s information lookup capabilities. EnterAct requires 2 Meg of memory minimum, 7-8 Meg for big projects. The price of power. A minimum configuration that provides all-round pleasant performance: 68040 @ 25Mhz, 12Meg RAM installed, Virtual Memory ON, 7 Meg partition for EnterAct, 1/2 Gig hard drive, System 7.5.3. And at least an 832x624 screen, preferably 1024x768. EnterAct is intended for creating, maintaining, and reviewing Symantec, MPW, and MetroWerks C/C++/Java code. You may in rare cases find one or two small difficulties right at first (see DON’T GIVE UP just below) but you should find that EnterAct understands your C/C++/Java, and even your “C--” (first-draft stuff). Feel free to print this manual (use EnterAct so the pictures will print). The benefits of having it on disk are that you can use Find on the table of contents and elsewhere to jump to topics of interest, and that this document is marked with chapter headings—hold down the <Command> key and click in the title bar to view the marker menu for this file. You may also encounter this doc in HTML form. - - - - - - - - - - - - DON’T GIVE UP - - - - - - - - - - - - DON’T GIVE UP if you attempt to "Update Dictionary" and the parser complains about your perfectly good source: quite often, this first problem will be your last, and easy to fix. (Note with v3.0.5 EnterAct is smarter about handling complicated preprocessor tangles -- if you get stuck, please let me know and I will try to fix the problem at my end. My tech support address is up above. As of this writing EnterAct runs into problems only with rather pathological practices, such as duplicated comment starts [this check can be turned off in the Options dialog], aliases for keywords, and one or two other oddities as described in the "Source code restrictions" chapter.) The commonest problem involves conditional #defines which duplicate important punctuation (here '{'), such as ____ #ifdef GO_LONG long GetArrayIndex(void) { #else short GetArrayIndex(void) { #endif ____ —although this particular example doesn't bother EnterAct. If you do run into a problem it will almost certainly be something similar, involving duplicated punctuation such as the two '{'s above. The fix for this sort of problem is to recast the definition slightly to remove the duplicated punctuation: ____ #ifdef GO_LONG long GetArrayIndex(void) #else short GetArrayIndex(void) #endif { ____ Similarly, if a construction such as ____ struct Thing #ifdef _cplus_ : public BaseThing #endif {.... ____ causes a problem it will work fine if recast as ____ #ifdef _cplus_ struct Thing : public BaseThing #else struct Thing #endif {... ____ although once again this example is handled correctly by EnterAct. (Note in this case the definition that appears first will be the one that appears in your Browser window.) Nested comment starts ( /*.../*...*/) will also cause the parser to hiccup. Best, fix the comment so it has one start and one end. Second best, pick "Options" from the Edit menu and deselect "Detect nested comment starts". - - - - - - - - - - - - CONTENTS - - - - - - - - - - - - (Each line in quotes «» below is a "Go to" link: to go to a chapter, click on its line and select "Go to" from the Search menu. For more on "Go to" links, see chapter 17. These chapter links are available in the popup marker menu, which you can bring up by holding down the <Command> key and clicking in the title bar. Section names are also listed here, though they are not links or markers: to go to a section, select the name including the '§', and then use "Enter Selection" and "Find Again" from the Search menu. While within a chapter, you can advance from section to section by searching for just the '§' character, which is an <Option><6>.) «01 Introduction» «02 About EnterAct» § When to use EnterAct § An overview § Looking ahead «03 Getting started» «04 Definitions and conventions» (chapter 05 has been deleted) «06 Whirlwind tour» «07 Source code restrictions» § Why not just compilable code? § Aliases § Obviously unnecessary parentheses § Nested comment starts § Preprocessor tangles § All–or–nothing macro’s «08 Projects» § Introduction § Project files § Creating a project § Selecting your <system> folder § Three panes—.c, .h, plain text § Adding Java files § Add Files—the one-at-a-time way § Adding files from a list § Add All In Folder—the fast way § Add Mac Headers § Add THINK Headers § Add Standard C Headers § The active pane § Remove File § Remove •'d Files § Custom file extensions § Distinguishing ".h" from <.h> § Copy and search in the project window § Project memory needs § Multi-file selection § Project context restoration § Switching to other projects § Tips «09 Dictionaries» § Introduction § What’s in a dictionary § Building your dictionary § Keeping it up to date § How long will it take? § Show Dictionary «10 Lookup» § AutoLook § Regular lookup (press <Enter>) § <Enter> for lookup, advancing, scrolling § Looking up the clip (press <Command><Enter>) § Reverse lookup (press <Shift><Enter>) § “Sounds like” lookup (press <Option><Enter>) § Viewing other entries in lookup windows § For faster lookup § Hints with lookup § Number of lookup windows § Number of entries per lookup § Keeping lookups around § Looking up your notes § EnterAct as a "definition finder" for other editors § Looking it up with THINK Reference or Toolbox Assistant «11 Seeing where a term is defined» § <Option>double–click § Find Definition § If there are multiple definitions § Other ways of finding definitions «12 Browsing» § The Browse command § Finding classes in the Browser window § Method and class popups § Browsing classes without the browser § Browsing methods without the browser «13 Documents and windows» § New, Open, Close § Save, Save As, Revert § Close and Save Documents § Autorevert § Modify Read Only § Saving window locations § ... without being pestered § Newly opened windows can be long or short § <Option>–Zoom zooms just the length § Number of windows at one time § The Windows menu § The display box § Printing «14 Editing» § Introduction § Undo § Typing, Cut, Copy, Clear § Paste preserves indentation § Drag and Drop for text § Code templates § Selection: front, non–front § Paste Selection Behind § Font, font size, tabs § Shift Left / Right § Reformat Selection § Syntax coloring § Graphic nesting display § Arrow keys for moving around § Illustrating your text «15 Balance» § Checks everything § Shows the error location § Balancing a file § Balancing a specific delimiter § Nested and bad comments § Starting in the middle § The asm problem «16 Search» § Introduction § Find is modeless § Find options § Batch Find options § Dual Batch Find § <Tab> and <Return> § Find again § Enter selection § Recent finds are remembered § Replace § Replace and Find Again § Replace All § Multi–file searches § Skip '-' : excluding files from a search § THINK Find commands «17 “Go” commands» § Go to Top/Bottom § Go to § Going to included files § Going to text positions § Going to markers § Go Back «18 Markers and the Locations menu» § Introduction § Mark § Marker menus § Unmark § Automark § Copying marker names § The Locations menu «19 Options, under the Edit menu» § Introduction § Number of lookup windows § Number of entries per lookup window § Remembering window locations § Long or short windows § Reformat Selection options § Detect nested comment starts § Ignore 'ckid's § Relocate files automatically § Automark source files § Save source/headers marks § Append arguments for automarked functions § Record Find, Find Again, Find Definition «20 Switching to other applications» § Under the Finder (System 6) § Under MultiFinder (or System 7 or later) § Check the disk for changes § Working with THINK C «21 Show activities» § Introduction § What’s recorded § Recording limitations § Showing your recent activities § What’s shown § Temporary, obsolete, and undone activities § Updated file names § Reviewing activities § Selective single undo § Reverting a file § Turning activity recording on and off «22 "Index" commands» § Functions… § Cross-Reference… § #Includes… § Marker Names… § Potential Locals § Standard Metrics § Check Prototypes «23 Some thoughts on using EnterAct» § Projects are cheap § Learning from or reviewing code § On documenting your work «24 If there's a problem» § Out of memory § Dictionary problems § Lookup problems § Editing problems § Balance problems «25 License agreement, tech support» § Technical support § License «26 Appendix 1: Drag_on Modules» «27 Appendix 2: Calling hAWK programs» § Calling hAWK from the menu § Calling hAWK with a command line «28 Appendix 4: EnterAct as THINK's editor» § Requirements § Installing EnterAct as THINK’s editor § Starting a session § Working with EnterAct as THINK’s editor § Using THINK’s Find commands from EnterAct «29 Appendix 5: EnterAct and Code Warrior» «30 Appendix 6: the Scripts menu» (for all about the Drag_on Modules, please see «hAWK User’s Manual» and «Read Resource Manual» included with this package, as well as Appendices 1 and 2 here) - - - - - - - - - - - - Introduction - - - - - - - - - - - - Feeling slightly disoriented? That’s just the anesthetic wearing off. You now have several megabytes of new memory installed in your head, preloaded with the important facts on everything of interest in your source code. To access your new memory, click after the name of any function, struct, define, etc that you’d like to remember in detail, and glance at the "AutoLook" window. Welcome to EnterAct. If you’re at light speed, prepare for warp drive. If you’re learning C/C++/Java, you’ll find that the ability to look up anything of potential interest gives you more than total recall: you now have an on–line personal tutor. If you just want to use EnterAct as a "definition viewer" to help out some other editor, see the section § EnterAct as a "definition finder" (to get there, use "Enter Selection" and "Find Again" on the above line). This manual is not as impersonal as it perhaps should be, for which the author apologizes, however insincerely. My name is Ken Earle, I’m responsible to you for EnterAct’s performance, and since several of EnterAct’s editing enhancements will be new to you I will occasionally intrude a personal opinion or bit of advice. For the most part, though, you should put on your Adventure hat and expect to take EnterAct in your own direction. If you’ve done some programming in C/C++ on the Mac, you’ll find that EnterAct is very easy to get used to. EnterAct is intended to complement MPW, Symantec, or CodeWarrior (or Sun's Java), which you will need for compiling and testing your code. For creating, maintaining, learning from, and documenting code—read on. (§) 60 second warmup EnterAct uses a project window to keep track of your files, as does THINK C for example. However, the main purpose of an EnterAct project is to allow you to build a dictionary of all terms in your project, for rapid lookup. There are three panes in an EnterAct project window, containing your .c, .h, and documentation files from left to right respectively. The easiest way to add files to your project is to drag files/folder onto your project window. To build a dictionary, select “Update Dictionary”. Unless there are major errors in your source code, this will zip along at 2-3 files per second. (If you hit a problem, see DON’T GIVE UP up above, around line 131 for easy fixes to most problems.) Double–click on any file name in the project window to view a file. To look up a term, double-click on it, or click just after it (or of course type it in) and press <Enter>. Select “AutoLook” to put EnterAct’s automatic definition retriever on-screen, and it will keep up with you as you edit and click about. You should find that "AutoLook" by itself can fill most of your information needs. (§) Onwards What next? If you read straight ahead to the end of the “Whirlwind tour” you’ll have a good grasp of the basics. Reading the remainder of the manual at some point is a good idea. You will find that many things that were relatively complicated or tedious before, such as information lookup, integrating documentation with code, file and window management, picking up where you left off, etc, are now much simpler, some to the point of being completely automatic. Inevitably, when tasks become simpler, new possibilities and approaches spring to mind. You can use EnterAct as a replacement for THINK’s editor (THINK version 6 and later, the “use external editor” Edit option in THINK)—see Appendix 4 for the easy how-to. EnterAct also sends "touch" events to any running CodeWarrior compilation environment. After you feel comfortable with EnterAct, please take a look at the “hAWK User’s Manual” on disk. Many useful programs are supplied for this powerful little language, they’re easy to run, and hAWK does its work in the background. And remember, take a break every hour! - - - - - - - - - - - - About EnterAct - - - - - - - - - - - - § When to use EnterAct EnterAct is a standalone, project-oriented, language-aware programmer’s editor designed to smooth the process of creating C, C++, and Java code. You should find EnterAct useful for the following tasks: • requirements analysis, specification, and design document creation or review • creating, maintaining and reviewing source code • as a "definition finder", helping editors that aren't as aware • linking support documents and source code • debugging sessions that require extensive source code review • keeping a log of your activities • oddjobs such as multi-file search and replace, automatic source code generation, cross-referencing, algorithm prototyping, deleting or copying a list of files, etc etc (via “Index” commands and hAWK, both under the EnterAct menu). You'll need a compiler/debugger for compiling and testing your code, and a resource editor will round out your code creation environment. EnterAct can be used in place of THINK’s editor (the “use external editor” Edit option in THINK version 6/7). For the simple setup required, see Appendix 4. To use EnterAct as a "definition finder" with other editors: • read enough here to learn how to create a project, build a dictionary, and show the "AutoLook" window. Knowing how to call up "lookup" windows by pressing the <Enter> key is also useful. • when you're using the other editor, also run an EnterAct project with contents roughly corresponding to the code you're working on - have the "AutoLook" window open, as the frontmost text window in EnterAct. Your project dictionary should be reasonably up to date. • to look up a term with EnterAct; Copy it in the other editor, and switch to EnterAct. If you don't immediately see the definition in the AutoLook window (rare), press <Command><Enter>. To look up the class or struct that contains a particular member, press <Shift><Command><Enter>. § An overview EnterAct provides a variety of capabilities in several different areas to make creating and reviewing code simpler. As the following summary suggests, you do have a handful of new concepts to become comfortable with. But for the most part you’ll find just new ways of looking at old problems, and it shouldn’t be long before you take it all for granted. > Information management • each EnterAct project stores, for instant retrieval: • the prototype of every method and function (including static and in-line) • and the full definition of every class, struct, union, enum, enum constant, #define’d constant or macro, typedef, and variable provided the definition or declaration occurs at the top level of your project source code, or within a class. As a special case, #define’s within struct, union, and enum bodies are also recorded. (Hereafter, “definition” will be used as shorthand for “definition or prototype”). • Definitions can be stored for any C/C++/Java file you specify, including toolbox headers, standard library files, class source or headers, and of course your own source files, even if they are under development (typically EnterAct can tolerate or compensate for almost all first-draft errors and omissions) • the “AutoLook” window automatically displays the definition of any name that you select or click after, keeping up with you as you edit and mouse around. It also serves as a spelling checker • for more permanent displays of definitions, or to look up a term when you’ve forgotten its correct spelling, double-clicking on or clicking after the name and pressing the <Enter> key creates a separate window holding the definition. This is called "regular” lookup, and the resulting window shows either all variant definitions, if your spelling was exact, or closest matches, based on runs of matching characters, if your spelling was off • for phonetic or “sounds like” lookup, press <Option><Enter> instead • for reverse or “struct for member” lookup, press <Shift><Enter> to view all structs, classes, and unions whose definitions mention the name • results for regular, phonetic, and reverse lookup are shown in a new separate “lookup” window, politely sized and placed. Hold down the <Option> key and click in its title bar to select from a popup menu listing the definitions that were retrieved for the name being looked up • as a result of the above approach, you can show several definitions at once from the same file or different files in separate, self-managed windows. • EnterAct's "Browse" window does the expected things (and more), and works with first-draft C++ or Java code. And it looks pretty. > File and window management • an EnterAct project window has three panes, showing source, header, and documentation file names in separate alphabetical columns. Any file can be opened by double-clicking on its name (or hit <return>) • since Enteract is not a compiler, there is no need to set up code segments. As a result, EnterAct’s “Add All In Folder” command can add all of the files in a folder to your project with a single click (including, optionally, all files in subfolders), automatically placing source, header, and documentation files in their appropriate panes. Dragging files or folders onto a project window works the same way. • all Mac headers, THINK C headers, or standard C headers can be added to your project with single separate menu commands • multi-file selections (a generalization of multi-file searching) can be made right in the project window • windows can remember their screen location and size—and, if you so choose, won’t pester you about saving changes if all you changed was the location or size • when EnterAct opens a file for the first time, it bases the width of the window on the first 20 lines of the file • <Option>-zoom drops down the bottom of a window, not affecting the width. • text files are saved safely. Project saving is automatic, and this is threaded into the background when possible. > Editing • smart paste of code blocks reduces the need to “Shift” left or right • the “Paste Selection Behind” command combines Copy, switch to the window just behind, and Paste over what is selected there. It’s undoable (in EnterAct even “Replace All” is undoable), and to help you anticipate results the selection in your next-to-front window is outlined in a box • full Drag & Drop for text • “Balance” handles comments and strings, and can balance a whole file at once. If there is an error, you will be shown where it is • now and then, a picture is worth a thousand words. For these occasions, you can place and display a picture in any text document, even a source file (put it inside a comment, and the compiler will never know) -- search here for "Illustrating your text" > Context restoration • “project context restoration”: when you close an EnterAct project, it keeps a list of your project files that were open at the time; and when you later reopen the project, your working documents will reopen at the same time, placed on the screen where you left them (also called the “painless Quit”) • “activity review”: the “Show Activities” command displays a list of the last 10,240 things you have done, in plain English, with full contents of all text inserts and deletes. With this display, you can: • review your progress when making complicated changes • accurately bring your “Log” or “Version History” up to date if you let this lapse for a bit • selectively undo a single activity • revert files to recover earlier versions • “safe switching”: EnterAct will optionally save your documents when you switch out, and refresh them from disk when switching back if you changed any with some other application. This restores the synchronisation between EnterAct and other applications, and helps prevent losing changes to a file. > Context alteration ("navigation”) • Automatic marking of source files whenever you open or save a file, including all function, method, and class definitions. (To access a document’s marker menu, hold down the <Option> or <Command> key and click in the title bar of its window) • “Go to” accepts a file name followed by line number, or file name followed by marker name, or any one of file name, line number, or marker name. Useful for: • putting fixed links in your documents with file name followed by line number (such as /* See App_Main.c 389 */ ) • maintained links, consisting of file name followed by marker name (such as /* See «MyApp Design Notes» «2.3 Custom Resources» */ To generate the text for a link of the form «file name» «marker name», hold down the<Shift> and either <Option> or <Command> keys while clicking in the title bar of the window that has the mark; when you select the mark from the resulting popup marker menu, the text will be copied to your clipboard. Both file and marker name may be abbreviated or slightly incorrect, eg /* See «Design N» «Custom Rez» */ • jumping to locations as reported in the “Show Activities” display • jumping to locations generated by hAWK programs ($CompareFiles, $MFS_SuperLister, and many others) and also locations generated by several of the "Index" commands, such as "Cross-Reference..." • “Go Back” lets you toggle between two locations, in one or two files • jumping to a definition (<Option> double-click) works with toolbox headers, first-draft code, and your own notes, almost always going straight to the definition with no stumbling over a mention in a comment, or a prototype. This allows you to use defined term names in source or documentation as true “hyperlinks”. • the Locations menu provides "global" (project-independent) markers. > The best little language in the world • “hAWK” is a project-oriented version of “AWK”. AWK has long been the C programmer’s little language of choice, and hAWK, with its simple “three clicks and run” interface, is as easy to invoke as any macro language (there's a command line too) • with one click, you can choose to have a program take its input from the front text file in EnterAct, or all files selected for multi-file operations in your EnterAct project • hAWK is a full programming language, modelled after C but simpler in many ways, with many additional built-in capabilities (especially for dealing with text) • use supplied hAWK programs to: generate a list of full path names for all files in a project, list all occurrences of a word or string or regular expression, copy or erase files, translate a C declaration into English, list all potential local variables in a C function under development, compare files, etc • and you can write your own programs to: check the contents of custom resources or file data, prototype algorithms, and in general handle any odd job having to do with text files that you can spell out an algorithm for (using the fullest implementation of regular expressions available anywhere) -- I'm working on "text to html" at the moment.... • as of version 3, you can write "magic clipboard" programs in hAWK that will monitor EnterAct's clipboard, and, when conditions you specify are met, will do anything you like to the clipboard's contents. Useful for mowing down repetitive but moderately complicated tasks (eg changing old-style C function declarations to the new prototype style, changing /**/ comments to //). Once your hAWK program is running, all you do is Copy and Paste. Typically these programs flash the menu bar to indicate that the clipboard has been altered. • "Code templates" make it easy to fire off a hAWK program by using a command line -- see «27 Appendix 2: Calling hAWK programs» below. > Using EnterAct as THINK’s editor • EnterAct works fine by itself, but if you have version 6 or later of THINK C and sufficient memory you can use EnterAct as a replacement for THINK’s own editor (this is the “use external editor” option described in your THINK manual). • using EnterAct as THINK’s editor eliminates the need to “Make” your THINK project when bringing it up to date, since THINK C will automatically be made aware whenever you change a source file with EnterAct—and all of EnterAct’s best features, such as info display and hyperlinking, will be available within THINK C. For the details, see Appendix 4. > Using EnterAct as CodeWarrior's editor • EnterAct sends "touch" events to any open CodeWarrior project, so CodeWarrior will be able to keep track of which files need recompiling. > Using EnterAct as a "definition viewer" with other editors: • Have EnterAct with an appropriate project running while you use the other editor. Your dictionary should be reasonable up to date, and the AutoLook window open • Copy a term in the other editor, and switch to EnterAct for instant definition display in the "AutoLook" window • If you don't see an instant definition, try <Command><Enter> for spell-tolerant lookup of the clip to a separate lookup window • To look up the struct or class containing a copied member name, press <Shift><Command><Enter> (When looking things up with the <Enter> key, <Command> is for Clipboard, and <Shift> is for member lookup -- also called "reverse" lookup, so remember "<Shift> into reverse"....) > Miscellaneous • EnterAct’s “Print” command can print illustrated documents, and always folds back long lines rather than clipping them off • “Reformat Selection” lets you clean up plain text documentation, including long comments. It was used to maintain this document • “Save As” can be used with projects, so you don’t have to start over each time • “Index” commands under the EnterAct menu: function call/called by lists, cross-referencing, lists of markers or #included files, and “Potential Locals”, which helps ease the declaration of local variables (note most of these are for use with C code only, sorry) § Looking ahead It would be best at first to focus on building EnterAct projects and exploiting the various ways of looking up definitions and navigating around. For the necessary background, read straight ahead here to the end of the “Browsing” chapter. The one vital new skill to master is that of pushing the <Enter> key to view definitions, although the "AutoLook" window will almost always beat you to it. After the “Browsing” chapter, topics become relatively independent. “Switching to other applications” is recommended reading, since as mentioned above EnterAct will save documents when you switch out and refresh them from disk when you switch back, and you should either agree with this approach or turn this option off. And before starting in on the “hAWK User’s Manual” on disk, it will help to be familiar with EnterAct’s approach to multi-file searching, as explained in the “Searching” chapter. For some fun, check out "§ Code templates" below. For help with any difficulties that might pop up, see the “If there’s a problem” chapter towards the end of this manual. - - - - - - - - - - - - Getting started - - - - - - - - - - - - (§) Installation You’ll find complete instructions for placing the bits and pieces that make up EnterAct on disk 1 in the file “Installing EnterAct 3/tt” (which starts up TeachText if you double-click it). There are two different approaches you can take: • drop some aliases into your "EnterAct Stuff" folder • move EnterAct into your compiler folder Recommended, drop aliases of your main development environment folders (CW, Symantec, MPW etc) into your EnterAct folder. When you are making a new project and are asked to select a <system> folder, select the appropriate alias. (§) What to do first If you don’t feel comfortable using your Macintosh yet, please take an hour or so to play with some other program before continuing. The Whirlwind tour will introduce you to the most important things. After a bit of pushing the <Enter> key and and playing with your new memory, you’re ready to start using EnterAct seriously—but it wouldn’t hurt to read the rest of the manual. (§) Please read these If you’re a multi–platform developer, please read the section on “All–or–nothing macro’s” in the “Source code restrictions” chapter. And you should know that EnterAct's default behaviour is to save all open documents when you switch out, as discussed in “Switching to other applications”, chapter 20. To avoid this, deselect the "Safe switching" option at the top of EnterAct's "Options..." dialog. (§) hAWK and Read Resource After becoming acquainted with EnterAct, add the “hAWK User’s Manual” and “Read Resource Manual” to an EnterAct project, open them up, and read along. Learning “Read Resource” takes 5 minutes. Learning to run a few hAWK programs takes an hour or so, learning to write them isn’t that tough—and it’s fun! Adapting your application to call hAWK will take a day or two. Changing hAWK is harder, but all the source is there. "hAWK" is a Mac interpreter for "AWK", which resembles C (though lacking C's more complicated features) with many built-in functions that let you dash off small programs to do nifty text manipulation. - - - - - - - - - - - - Definitions and conventions - - - - - - - - - - - - (Note menu commands may appear in quotes here but often are just capitalized. They are sometimes used as verbs, as in “when you Balance a comment...”.) Balance: checks all paired delimiters, and detects nested or improperly–formed comments. If you have an insertion point at the very beginning of the file, Balance will check the entire file. If there’s an imbalance, you’ll see where it is. Balance always includes the delimiters in the shown selection, because to exclude them is stupid. Definition or Entry: for functions and methods, the prototype or equivalent. For everything else (struct, #define, variable, etc), the full statement in which the term was mentioned or defined. Dictionary: the collection of terms and definitions for your project. Drag_on Module: a “mini application” packaged as a separate CODE resource, called as a C function. For instructions and code to call Drag_on Modules from your application, see the “code to call Drag_ons” folder on disk 2, and also the example Drag_on caller “Minimal App7”. While Drag_on Modules require some application to act as a “shell”, support for all callback functions by the calling application is optional. Two modules are included: hAWK, a Mac version of AWK (see “hAWK User’s Manual”) and Read Resource (see “Read Resource Manual”). If you follow the “Getting started” instructions, both modules will appear at the bottom of EnterAct’s “EnterAct” menu. Find Definition: given a selected dictionary term, opens the file where the term is defined and scrolls to the first instance of the term in the file. The equivalent of <Option>double–click, but in addition works with full method names, which contain colons. “Go to” link, “Go to” selection: text typically of the form file-name marker-name where “file-name” is the name of an EnterAct project file and “marker-name” is the name of a marker in the file, with optional European-style quotes around either part (for example, «MyProj.LOG» «To Do» ). To open the file and go to the marked position, select the file-name marker-name text and use the Go to command. Details are in “‘Go’ commands”, chapter 17. Insertion point: the flashing “|” cursor which marks your place in a text window when no characters are selected. Look up a term: to look up a term, select an insertion point just to the right of it, or double-click on it, and press <Enter>. A lookup window will appear. The AutoLook window shows definitions automatically as you type or edit (double-click on the term or click to the right of it, or type it in). Lookup window: a special kind of text window used to show dictionary entries. The title begins with “••” or “¶¶”. Often several entries are “stacked” in one lookup window; to cycle through them, press <Enter> with a range of characters selected -- or better, hold down the <Option> key and drag in the window's title bar to pick from a popup menu. Menu commands are often quoted, always capitalized. Paired delimiters: • () round brackets, or parentheses • [] square brackets • {} braces, or curly braces • /* */ comment start and end, together a comment • " " double quotes, around strings (continued across lines with “\”) • ' ' single quotes, or ticks. Paste Selection Behind: will Copy the selection in the front window, switch to the next window, and Paste over what is selected there. The selection in the next–to–front window will be shown by a two–pixel wide black border. Project: a three–pane window containing any group of source, header, plain text, and PICT documents. Selecting Update Dictionary builds a dictionary for all source and header files. Both the file list and the dictionary are kept on disk in the corresponding project file. Double–clicking on a file shown in the project window will both open the file and send the project window behind all other windows. It can be brought to the front again with the Windows menu, or <Command><zero>, if it’s hidden. Range of characters selected: white text on a black background in the front window, seen for example when you drag over some text. In the next–to–front window, the selection range is shown outlined in a black box rather than white on black (the next– to–front window is affected by Paste Selection Behind, and by some Search commands when the Find dialog is in front). Recent activity: a full specification of something you’ve done recently with EnterAct, as presented in the “••Recent Activities” window generated by the Show Activities command. All significant activities are recorded, including cut copy paste typing find replace new open close revert start quit. Recorded details include time, location, and contents if it was an insert or delete. For details see the “Show Activities” chapter. Reformat Selection: evens out the line lengths in a range of selected text, with maximum line length and ragged right versus full justification as specified in the Options dialog. Intended for use with comments or plain text, rather than code. Regular lookup: double-click on or click after a term, and press <Enter>. A lookup window appears, holding all definitions of the term, or closest matches based on spelling if your spelling was off. <Option>click in the title bar for a list of definitions. Reverse lookup: select as for regular lookup, but press <Shift><Enter>. The resulting lookup window holds all struct, union, and class definitions which mention the word(s) being looked up. <Option>click in the window's title bar for a list of containing definitions. Sounds-like lookup: select as for regular lookup, but press <Option><Enter>. Like regular lookup, but not case-sensitive, with closest matches based on sound rather than spelling. <Option>click in the resulting lookup window’s title bar for a list of definitions. Specific single keys are placed in <>, eg <Enter>, <Option>, <Return>, <period>. - - - - - - - - - - - - Whirlwind tour - - - - - - - - - - - - (§) Hum along This little tour displays EnterAct’s basic capabilities, to help you avoid that “lost in space” feeling. However, there is much of potential interest that is not covered here, so please at least browse through the rest of the manual afterwards. For an example project we’ll be using “Minimal App7”, the files for which are included with EnterAct. If you feel adventurous, substitute your own project for Minimal App below. To exactly follow the tour, you’ll need the files that make up “Minimal App7”, a minimal application that does nothing but call Drag_on Modules. The “Minimal App7 ƒ” folder contains the needed files. If you haven't moved it, it's still in your "EnterAct stuff" folder. (§) Create a project We’ll be working with the files that make up “Minimal App7”, and the first step will be to create a project for it. The project will list source, header, and documentation files, and also hold a dictionary of all terms of interest. Let's go! You're probably using EnterAct at this moment, but if not, Double–click on the EnterAct icon to start, and cancel the dialogs that appear. To make a project for Minimal App7: • pick "New Project" from the EnterAct menu • pick a nice location for your project, and give it a name such as “MinimApp7.e” • click the Save button • in the subsequent dialog that appears, asking you to pick a <system> folder, pick your favorite development environment's folder (CW, Symantec, MPW etc) -- or if you have put an alias for the folder inside your EnterAct folder, pick it instead (IMPORTANT, some development environments contain multiple versions of the toolbox headers -- eg for CW select the "MacOS Support" folder) • A three–pane project window will appear. (§) Add some files You can add files to your project one at a time with the Add Files command, and there are are other menu commands to add all files in folders, all files in subfolders, and even all files from a list of full path names (hold down the <shift> key and look under the EnterAct menu for the last two). But we're going to do it the easy way first: switch to the Finder, locate the folder called "Minimal App7 ƒ" inside your main EnterAct folder, and drag it onto your new project window. All files in the folder will be added to your project. There is no need to ever select one of the three window panes when adding files. The left pane is for your source files (.c), the middle for all header files (.h), and the right pane is for all other text files (and PICT’s). EnterAct selects the correct pane for each file automatically. For our project we’ll also want the toolbox headers and MW or THINK C headers. To add these to your project, hold down the <Shift> key and select Add Mac Headers. All of the standard toolbox headers, and, because of the <Shift> key, all THINK C headers, will be added to the middle (header, or “.h”) pane of your project. If you don't have the THINK C headers, omit the <Shift> key (or ignore any error message). If EnterAct complains that multiple versions of the toolbox headers were found, use the "Select <system> folder" command under the EnterAct menu to select a more specific subfolder within your development environment folder (eg for CW select the "MacOS Support" folder. And for good measure, use the Add Front File command to add this document to your project. At this stage, your project should look something like this: ____ source pane header pane documentation pane ____ For illustration purposes the project window has been kept small, but feel free to make it as large as you like. The project window will go to the back when you double-click on a file name to open a file, and it can be brought to the front from the Windows menu if it’s hidden. (§) Build a dictionary (".c" and ".h" are used as shorthand for source and header below) Your dictionary will contain all terms in your .c and .h files that are defined or mentioned outside of a function, struct, or union body. To build, it, select Update Dictionary from the Project menu, and sit back for a few seconds—this shouldn’t take long, typically under 1/2 second per file on a Mac II. If a major problem or bug does interrupt the dictionary build, you’ll see a message telling you what’s up. You can either fix it and reselect Update Dictionary, or, with the offending file selected in the project window, select Remove File followed by Update Dictionary to go on with this tour immediately. (See DON'T GIVE UP near line 110 above for fixes to common problems.) If you are pursuing your own project instead of Minimal App7, you may run out of memory when building your dictionary. If this happens, either increase the amount of memory allocated to EnterAct by one Meg and try again, or see “EnterAct Memory Needs” on disk 1 for a detailed guide to estimating memory needs. Two megabytes can handle a small project, but a real whopper may need seven or more. (§) Viewing definitions and prototypes If you’re following along with the Minimal App example, open “minimalApp7.c” by double-clicking on its name in the left pane of your project window. To arrive at the right position for our example, select Find from the Search menu, type in "waitnextevent(", click the "Ignore case" button, and then type <Return> or click the OK button until you see the following: Now is a good time to activate the AutoLook window: first free up some room on your screen (a couple of inches at the bottom will do) and then select AutoLook from the “EnterAct” menu. It explains itself. For a quick look at a definition, either click just after a term or double-click on it: the definition will appear instantly in the AutoLook window. As an AutoLook example, return to the “minimalApp7.c” window and double-click on gEvtDetails, on the same line as WaitNextEvent(: You will see a definition of gEvtDetails appear immediately in the AutoLook window. And, you also see a complete definition of EventDetails. As you can see, the AutoLook window resolves variable, struct, and typedef tangles to show you all the relevant definitions. It also resolves #define’d “aliases” such as “#define H Handle”. For functions, you’ll see a prototype, with function name and parameters preselected so you can quickly paste a “template” for the function call into your code (by switching to the AutoLook window and selecting the command Paste Selection Behind). Basically, if the name is defined outside of a function body, the AutoLook window will show you the essentials you need to use it. The only requirements are that a file containing a definition (or prototype) for the name should be in your project, and your dictonary should be up to date for that file. As of version 3, EnterAct's AutoLook window will also display definitions of local variables, and provide more useful lookup for struct and class member names when you double-click on them or click after them. For this to work, your file should be a source (left pane) or header file, though not necessarily added to your project, and you should have your dictonary reasonably up-to-date. And AutoLook will also display relevant definitions when you type the name of a struct, class, or union member. By itself, the AutoLook window can supply most of the details you need to program or review nonstop. However, the display in this window is transient, keeping up with you as you click or double-click about, or type for that matter. To produce a more permanent display of a definition or prototype, more work is required on your part: you have to press the <Enter> key. To see it work, double-click on EventDetails in the AutoLook window, and then press the <Enter> key: Your screen may not look exactly like that, but you should see the definition of EventDetails appear in a separate window, called a “lookup” window. A press of the <Enter> key produces a separate window containing the information you’re after, definition or prototype. As you’ll see shortly, these separate “lookup” windows can take care of themselves. And the “press <Enter>” style of lookup also works when your spelling of a term is off, but still “distinctively close”. In general, you can look up any function, method, struct class union or enum tag, enum constant, typedef, or variable (including low–memory and statics) that is defined or mentioned anywhere in your .c or .h project files outside of a function, struct, or union body—and any #define’d constant or macro that is defined outside of a function body. In other words, just about everything of interest except local variables or any other “thing” which is meant to be used only within a single specific function. Note the AutoLook window does show local variables and data members. As you’ve seen, the fastest and easiest way to look up a definition for a term is to double-click on it with the AutoLook window on-screen. You can also click just after the term, or type it, and the AutoLook window will keep up. It will also often show class member and inline method definitions, after a slight delay. However, the AutoLook window has three shortcomings: • the display lasts only until you look up some other term • your spelling of the term must be correct • the display in the AutoLook window doesn’t update as you click about or edit in the AutoLook window itself. To overcome these shortcomings, the “press <Enter>” style of lookup produces a separate window holding one or more definitions of the term being looked up. To look up a term in this way: • double-click on it, or click just to the right of it, or type it in • and press the <Enter> key. A dictionary entry for the term will appear in a new small text window, called a “lookup” window. Lookup windows are mostly like text windows, the key differences being that they cannot be directly saved (Copy and Paste to a real text window to do that), and they usually can show you other dictionary entries. Only one is shown at a time. If your spelling is off, the window will show best guesses rather than exact matches. (To view other entries, <Option>click in the title bar.) (§) Lookup window frames In the small display box along the bottom of the lookup window you will see: the name of the file from which the entry was taken; the kind of term it is (a one–letter abbreviation, for example “v” for variable, “(” for a function, “s” for a struct); and two numbers—the current entry you are viewing, followed by the total number of entries currently stored in the lookup window. The title of the lookup window will be the term you wanted looked up, preceded by two bullets, eg “••EventDetails”. The two bullets are a sign that the window is a (temporary) lookup window, not a regular document window. (§) Viewing other entries in a lookup window A lookup window may hold additional definitions if: • there are variant definitions of the same term, such as defining and declaring instances of a global variable, or prototype and defining instance of a function • the same term is used in different ways, such as a struct and a typedef with the same name • your spelling of the term was incorrect: in this case, closest matches will be shown, and the number shown is under your control. Numbers in the display box of the lookup window indicate which entry you’re viewing, followed by the number of entries available: if the numbers read “1/1”, then only one is present; whereas if the second number is greater than one (from “1/2” up to “1/60”) then more entries are “stacked up” in the window. To view a different entry, hold down the <Option> key and click-and-drag in the window’s title bar to select from a popup menu. To produce a sample, type "KeyDetails" in any text window and press <Enter> to produce a regular lookup window; this term doesn’t match anything in the project, so closest matches are shown. From the designation “1/4” in the display box, you can tell that four entries are contained in the lookup window. To access them, hold down the <Option> key, click in the title bar of the “••KeyDetails” lookup window, and select from the resulting popup menu: You can use <Command> instead of <Option> to view popups if you prefer. (Truncated full path names are also shown in the popup menu, to help you pick the exact definition you want.) Each entry in the popup begins with a one-character “hint” describing the definition type, eg “t” for typedef, “v” for variable, “(” for function. For a complete list, see “Hints with lookup” in the “Lookup” chapter. You can also cycle forwards through the entries in a popup window by repeatedly pressing the <Enter> key. Press <Option><Enter> to cycle backwards. Normally <Option>-clicking in the title bar is handier because it gives you an overview of all the entries. (§) The <Enter> key In any text window including lookup windows, pressing the <Enter> key with an insertion point means “look it up”. The I–beam should be just to the right of the term you want looked up. Pressing the <Enter> key when characters are selected also activates regular lookup in a non-lookup window, and in a lookup window the result of pressing <Enter> is either regular lookup or cycling to the next match. In a lookup window, if the selection agrees with the name of the term being displayed or if your selection is so large that lookup cannot be done, then <Enter> will cycle you to the next entry; conversely, if your selection is not the name of the definition being shown and your selection could be looked up (one word, or two words separated by colons) then <Enter> will look up your selection. Note that pressing the <Enter> key for separate lookup is meant for use with names that are in your dictionary, and in particular local variables are not included. To look up the struct or class that contains a particular member, press <Shift><Enter> as described below. Whenever you display a new definition in a lookup window, a selection in the window is made for you. Among other things, this selection guarantees that if you press <Enter> or <Option><Enter> you will cycle back and forth through the definitions, rather than looking something up. Basically, you don't have to remember anything here since it all comes down to intention: if you intend to look up a name, selecting it and pressing <Enter> will do just that. If you intend to cycle to the next match, pressing <Enter> will do that instead. In the rare case that you change the default selection in the window and then wish to cycle, either pick from the popup menu or do a Select All before pressing <Enter>. (§) Looking up something in a lookup window Click to get an insertion point just to the right of the name you want looked up, and press <Enter>. With any name except the name of the definition currently being shown in the lookup window, you can also double-click on the name and press <Enter>. (§) Keeping the lookup around You can adjust the maximum number of lookup windows you wish to have on–screen at one time, with the Options command: when this limit is reached and you press <Enter> to see another lookup, one of the lookup windows that is currently on–screen will quietly go away to make room for the new one. To prevent this happening to a lookup window that you’d like to keep around, select Keep Lookup Around from the windows menu while the lookup window is in front. It will then stay on–screen until you close it, or until you close the project. When you “keep around” a lookup window, the two bullets “••” at the start of the window title will change to “¶¶” to help you distinguish the keepers from the ones that might go away later. (§) If your spelling is off If you press <Enter> for lookup and your spelling did not match any term in your dictionary exactly, then you’ll see whatever entries come closest, with suppression of variants on the same name in order to maximize the variety shown. The entries will be presented in order from best match to worst as you press <Enter>. EnterAct is very nearly as good at judging what’s close as you are, even though it doesn’t “understand” the terms being looked up. This perhaps surprising ability results from the natural tendency to give distinctly different names to terms with distinctly different meanings. You’ll find more about this in the “Lookup” chapter, but EnterAct’s lookup power is sufficient that one guideline is all you need: when you’re not sure of the correct spelling, type your best guess, remembering that C is case–sensitive. EnterAct will almost always retrieve what you want on the first try, among the first three entries in the lookup window. For an example with Minimal App, see the "KeyDetails" illustrations a couple of pages back. (§) Adjusting the number of lookup windows and entries shown EnterAct comes preset with a maximum of four lookup windows on–screen at one time, and a maximum of four entries per lookup window. You can change these limits at any time by selecting the Options command under the Edit menu. For complex problems, you may want more lookup windows. If your recollection of the spelling of a term has gone out the window, you may want to temporarily increase the number of alternate entries returned per lookup window. You can vary the number of lookup windows from 1 to 10, and the number of entries per window from 1 to 20. (§) Working with lookup windows You’ll probably find that the AutoLook window by itself can handle more than half of your information retrieval needs. And often you’ll want to have more permanent separate lookup windows showing data structures that you’re working with for more than a moment, and transient lookup windows to supplement the AutoLook display. Separate lookup windows are generated by double-clicking on or clicking after a name and pressing the <Enter> key, and made permanent by selecting Keep Lookup Around (the key equivalent <Command><K> is a good one to memorize). To help you manage lookup windows EnterAct places, sizes, scrolls, and makes selections in them for you, and also closes old lookup windows to make room for new ones. But the lookup windows have to go somewhere on your screen(s), and you’ll find the lookup process goes more smoothly if you leave some screen area free for the lookup windows to occupy. How much room you leave for lookup windows is best judged by experience, and will vary according to the needs of the moment. Some things to keep in mind: • lookup windows ignore the project window when looking for a place to appear • lookup windows prefer to occupy a small place rather than cover one of your working windows • if some window has to be covered by a lookup window, the lookup window will try to avoid your front two windows • lookup windows will try to appear right next to your front window, preferably below or above it. (§) Reverse lookup (<Shift><Enter>) On occasion you may find yourself viewing a member name and wondering what struct, union, or typedef contains it. Quite often, the AutoLook window will immediately display the definition you want. If not, double-click on or click after the member name and press <Shift><Enter> to invoke EnterAct's "reverse lookup". Here’s the result of double-clicking on "ioFDirIndex" and pressing <Shift><Enter>: (Note pressing just <Enter> would have produced the definition of ParamBlockHeader, not a list of structs or classes that contain it) As with all lookup windows, you can access the other definitions stacked up in it by holding down the <Option> key and clicking in the title bar to choose from a popup menu. Reverse lookup is not case-sensitive. Although it is called “struct for member” lookup elsewhere, it is actually slightly more, since it attempts to match your selection with something in a struct, union, or typedef without regard for whether it is a member name. Reverse lookup accepts arbitrary strings of text up to 255 characters (for this you’ll have to select the text to be looked up and then press <Shift><Enter>) and will match it against anything in a definition, even inside a comment. Aside from being case-insensitive, reverse lookup requires exact spelling—but your selection can be just part of a word, or several words with punctuation included. The AutoLook window will usually show struct-for-member lookup for a term. If you're inside a function in a source file then AutoLook will be on average more accurate at providing the correct definition. In any case, only the first containing struct or class will be shown. This lets you see prototypes for inline method definitions that are entirely contained in a class definition, and "fDataMembers", as well as regular struct definitions for some member. (§) “Sounds like” (phonetic) lookup The situation: “I’m desperate, show me a definition even if it’s wrong, all I can tell you is the name sounded something like this:”. The answer: type your guess and press <Option><Enter>. Your guess will be boiled down to a string of standard consonants, then compared with boiled-down versions of all your dictionary terms, and you’ll be shown the best matches. <Option><Enter> is not case-sensitive (it's only barely vowel-sensitive), and should be kept in mind as an emergency backup, for those rare occasions when regular lookup gives up on you. (§) Seeing where a term is defined The simple way is to <option> double-click on the term. To jump to the definition of a scoped name such as "thisClass::thatMethod()", <option>double-click on one of the names without releasing the mouse after the second click. drag over to include the other name, and let go. The "Find Definition" command does the same thing as <option> double-click, but also lets you select part of a word, such as just the "WindowData" part of "WindowDataPtr", before jumping away. As a Minimal App example, open a new window if you haven’t done so, type "gacc" , and <Option> double-click on it: You’re viewing the definition of the static variable gacc , which is used for communicating with Drag_on Modules. You will also be able to jump to the definitions of static functions, #define’s, struct, union, enum, and class tags, enum constants, typedef’s, methods—in other words, anything defined at the top level in your source files. If a member name is unique (used only in one struct, class, or union) you can <option>double-click on it reliably. If you can’t jump to a definition because your spelling is wrong, first look up the correct spelling first by clicking after the name and pressing the <Enter> key. Then, you can <option> double-click on the correctly-spelled name right in the lookup window. For the special case of multiple definitions of a term (eg several static variables with the same name), you need to tell EnterAct which one you want, and the way to do that is to do your <option>double-click in a lookup window that is displaying the exact definition you want. So the sequence is: • look the name up (select it, press <Enter>) • use the lookup window's popup menu to find the exact definition you want (<option>click in the window's title bar, and look at the truncated full path names shown beside each instance) • after picking the one you want from the popup menu, double-click on the term and off you go. Doing your <option>double-click in the AutoLook window won't work reliably with terms that have multiple definitions. If you're mildy annoyed at this point, use just the AutoLook window for a while, it will cheer you up. (§) Balance Balance checks all of the paired delimiters in C (with the picky exception of angle brackets <>). If you select an insertion point at the top of a file (with <Option><up arrow>, or Go to Top), Balance will balance your entire file. If any error in balance is detected, you’ll be shown the mismatched or unmatched delimiter. When balancing a file, if you hear a beep and the insertion point remains at the top of the file, that means your whole file balanced. As a shortcut, you can double-click on a delimiter. Balance also detects nested comments, and more importantly any single failure to properly start or end a comment, something even most compilers don’t do. Since EnterAct’s dictionary–builder checks comments fully, simply by building the dictionary you will guarantee that no improper comment in any of the included source files will ever generate a wild pointer or an uninitialized variable. If your source code deliberately contains nested comment starts, select the Options command and uncheck the “Detect nested comment starts” box in the "Parse" panel. (§) Searching The Find dialog in EnterAct is modeless, which means that when the Find dialog is in front any search command you pick will apply to the window just behind it. An important exception is Replace All, which works only when a text window is in front. The "Find" button in the dialog is the exact equivalent of the "Find Again" menu command. Both can be used with the project window itself by the way, to find file names in long lists. A popup menu at the top of the Find dialog remembers the 20 most recent strings of characters that you have searched for. The little buttons in the lower–right of the Find dialog allow to to set up a “coarse” multi–file search of your project files. As you click them, you’ll see bullets appear beside files to be searched in your project window. If you click the "Batch" check box, your multi-file search will be done all at once, and the results presented in a text window (file name, line number, and the full line where found). To go to a particular found instance, click on the line and use "Go to...". To “fine–tune” your multi–file selection, hold down the <Option> key and click on or drag over the file names right in the project window. Try it out now by clicking and dragging in your project window with the <Option> key down and you’ll see that it acts as a toggle, selecting files if they were not selected and vice versa. Your multi-file selection can also be used with the Remove •'d Files command, and as input to a hAWK program (which makes setting up a program run a trivial thing). (§) Adding marks to a source file EnterAct's default behaviour is to automatically provide marks for all functions, methods, structs and classes in a source or header file, to append a brief summary of arguments for all functions and methods, and to not save the marks with the source or header file. For documentation, EnterAct does no automatic marking but does save any marks that you add manually when you save the file. Normally this is all you need. To access the popup menu listing marks for a file, hold down the <Option> or <Command> key and click-and-drag in the title bar of the file’s window. Just select a mark and off you go. EnterAct’s markers are compatible with THINK C and MPW, indeed the suspicion is that there is only one kind of marker in the universe. Markers can be added “manually’” to a document, most commonly to mark section or chapter headings in your documentation. For an example, see the online version of this manual, or the “hAWK User’s Manual”. For the details on markers, please see the «18 Markers and the Locations menu» chapter. The "Automark" command under the Search menu provides some additional options. But the slight advantage of being able to mark additional points in your source file is usually outweighed by the nuisance of having to use the "Automark" command when you change the file. See the «18 Markers and the Locations menu» chapter for details, but I'd recommend against using the "Automark" command in its present form. If you would really like a more useful version of this command, let me know (kearle@interlog.com). Here's what the dialog looks like: (§) Going to markers in other files As an aid to linking source files with supporting documentation, EnterAct gives you a way to jump to a marker in any project file. This is done by selecting text in any window that consists of a project file name followed by a marker name, and then issuing the "Go to..." command. EnterAct can generate the necessary file name and marker name for the link, as follows: • in the window for the document in whch the marker is defined, access the marker menu and pick the mark, but in addition to holding down the <Option> or <Command> key hold down the <Shift> key as well • the necessary text will be placed on the clipboard, ready for pasting. The file name and marker name will each be surrounded by «» quotes, which are optional but help the text to stand out. • since you ended up at the mark's location as a side-effect, you can get back to your original location in the file by using the Go Back command. • to generate the text for all markers in one or more files, you can use the "Index Marker Names..." command (chapter 22). However, this works well only with documentation, since the marks for source and header files are by default not saved. A typical “Go to” link looks like ____ /* See «EnterAct 3 Manual» «13 Documents and windows» */ ____ and if the file “EnterAct 3 Manual” has been added to your current project then you can jump to the marker named “13 Documents and windows” by clicking anywhere on the line and using the "Go to..." command. The advantage of this kind of link is that since the marker position is maintained as you edit, so is your link. With this «file name»«marker name» style of link, both file and marker name can be abbreviated, and the link is immune to minor variations in spelling. Many variations on “Go to” are available, such as going to a file-name line-number, or just a file name, marker name, or line number. For details, see the “‘Go’ commands” chapter. (§) Keeping track of things When you close a project, it remembers which project text files you have open. Later, when you reopen the project, those text files are reopened as well. This makes it a little easier to pick up where you left off. You could call this “context restoration”, though some like to call it the “painless Quit”. It’s all automatic—just close the project before you close your working files, or if you’re quitting, don’t bother to close your working files first. The concept of “undo” takes a step forward with EnterAct’s Show Activities command, which displays the last 10,240 things you have done with EnterAct. Descriptions are in plain English, and full contents of edits are shown. A typical entry looks like this: ____ ¶45 Tue, Mar 9, 1993 7:45:11 pm TYPING «Untitled-1» 1 1 (obs) =>inserted 15 characters: «AdjustTheCursor» ¬ ____ —where “«Untitled-1» 1 1 (obs)” means the action started in the “Untitled-1” window at line 1, character 1 on the line (ie the start of the file), and the typing is now “obsolete”, ie it was never saved to disk before closing the window. The “file name - line number” part of the activity record is compatible with EnterAct’s “Go to” command. And the full contents of all inserts and deletes are shown, up to a very large limit. By using "Go to" and the contents of the activity record you will be able to locate and selectively undo any of your recent activities, provided that you haven’t destroyed the context of the edit with a huge delete or by erasing the corresponding file. To help you locate the edit position, Show Activities provides the option of correcting the original positions of edits to reflect the effects of other edits, which is normally what you’ll want when reviewing or selectively undoing your recent activities. Since there are new concepts here, the “Show Activities” chapter goes into considerable detail on such topics as “obsolete edits” and “updated activity positions”. Once you’ve read through it, you’ll realize you knew most of it already—you just didn’t talk about it much EnterAct saves your activities to a disk log as you work. So “undo” capabilities are not lost just because you quit and restart. There is a way to undo files (one at a time) back to specific activities. This involves the use of a hAWK program, and you’ll find the details in the “Show Activities” chapter. If you anticipate needing to do this, I would recommend using some sort of real version control rather than EnterAct to revert a file to a previous state. Though you haven’t done much yet, it wouldn’t be a bad idea to call up the Show Activities dialog, pick any old options, click the OK button, and see what happens. Not something you’ll use every day, but your last ten thousand activities are still there if you need to review or undo them, or figure out what the heck you just did. (§) Classes and methods When you build yourself a project that contains classes, try out the Browse command to see a graphic view of your classes. Double–click on a class name to view the class definition, click–and–hold briefly on a class name to select from a list of methods, and then view the method definition. If you’re new to C++ or Java, you’ll find no better way to learn than by exploiting EnterAct’s project–building, lookup, and browsing power—in fact, you might want to build a project for a TCL or PowerPlant demo or somesuch right now. (Color is recommended for viewing the browser) (§) Little things worth knowing If you hold down the <Option> key while clicking in the zoom box of a window, only the length will be zoomed. Without covering up your AutoLook window. When you double–click on a file in the project window to open the file, the project window will retreat behind all other windows. You can bring it to the front with <Command><zero>. Even on small screens this allows you to have a large project window and use it conveniently as a “mini Finder”. Paste preserves relative indentation, at least in the commonest situations where you would want your indentation to be retained( see the “Paste preserves indentation” section in the “Editing” chapter). Windows remember their last saved location, unless you select otherwise from the Options dialog. EnterAct takes special care of your text documents, ensuring that disk files are updated when you leave EnterAct, and windows are updated when you return to EnterAct (see “Switching to other applications”). This is the default behaviour. You can turn off the automatic saving and restoring if you want--but keep in mind that the "Show Activities..." command can show you the last 10,000 things you did, in the rare case where you chop something important out of a file and then switch out. Reformat Selection is handy for making comments pretty again after you’ve chopped them up (it’s undoable, and some options are available in the Options dialog). There are some other things worth trying out, such as full Drag and Drop for text, code templates, Dual Batch Find -- hey, take a browse through the rest of the manual when you have a minute. (§) Source code restrictions (don't panic) There are three sorts of code constructions that are nominally correct, but throw off EnterAct’s dictionary–builder. Please read the next chapter "Source code restrictons" if the very notion bothers you. Or just go ahead and use EnterAct, but remember that if you do run into a problem while building your dictionary there are simple workarounds for all problems in the "Source code restrictons" chapter. (§) Onwards If you’ve tried things out for yourself while taking this tour, I expect you know enough about EnterAct to begin using it full–time for code creation and review—aside from knowing when to poke the <Enter> and <Option> keys, there isn’t much to the basics. Eventually, alas, you should probably read the rest of the manual. Personally, I enjoy reading manuals. To acquaint yourself with hAWK and Read Resource, add the “hAWK User’s Manual” and “Read Resource Manual” to an EnterAct project and follow the instructions therein. Learning Read Resource is a 5 minute job. hAWK is rather more complicated, but it’s a powerful, widely–used little language and learning it should prove well worth the effort. Running hAWK programs is easy, at least, and many useful programs are included. - - - - - - - - - - - - Source code restrictions (ayeee! I knew it!!) - don't panic - - - - - - - - - - - - § Why not just compilable code? EnterAct is able to identify terms in your code and correctly deduce the type and definition of each term without doing extensive preprocessing or semantic analysis. The benefits are lightning speed, considerable tolerance of first–draft errors, and full information retrieval, definition finding, browsing, and automatic marker placement available right from the beginning of the code creation process. This is all made possible with EnterAct’s Heuristic Adaptive Reentrant Parser, which is based on a description of the way people actually write code and the importance they attach to various constructs, rather than on the textbook prescription. The drawback is that EnterAct cannot deal with absolutely everything that is possible in C/C++/Java, and some minor restrictions must be satisfied in order for the dictionary–builder to deal properly with your code. In practice, only the “illegal aliases” will present a significant problem if present, in that the only workaround is to remove them (have you ever seen one? me neither...). Obviously-unnecessary parentheses will result in extra or missing dictionary entries for some terms. Troubles with aliases and parentheses are extremely rare, since they obfuscate the source code for beginner and expert alike. To overcome problems with nested comment starts or “all-or-nothing macro’s”, you just need to make EnterAct aware that they are present, as explained below. § Aliases Defined equivalents for certain keywords and punctuation should be avoided. A defined equivalent or alias takes the form ____ #define Record struct ____ for example. EnterAct won’t know that “Record” is supposed to mean “struct”, and the dictionary–builder won’t work well at all. Keywords that should not be aliased: ____ asm enum pascal Pascal struct typedef union void class ____ Punctuation that should not be aliased: ____ ; : , \ " ' {} () [] / * = ____ You will never see aliases for any of these in published code, or in any code intended to be read by more than one person, for the simple reason that such a creature as ____ Record fileData BEGIN int x SEMI END SEMI ____ would be rather difficult for anyone but the author to read. Other aliases, such as ____ #define EQ == ____ are perfectly OK, by the way. § Obviously unnecessary parentheses These are just as rare as the aliases above. This restriction applies only outside of function bodies and refers only to parentheses that would result in a variable declaration resembling a function declaration. An example would be ____ Peter (Harvey); ____ Right now you know as much as EnterAct does when it runs into this sort of thing—is it a variable declaration or a function declaration? You may have deduced that the above declaration is almost certainly for a function “Peter” returning an (implicit) int, since you would never type those parentheses in a simple variable declaration, ____ int (x); ____ —these are an example of what is meant by “obviously unnecessary parentheses”, namely parentheses that make the code harder to read, not easier. If you avoid these excessive parentheses when declaring variables outside of a function, that’s all that’s needed. Once again, you won’t see them in any published code, and even beginners feel that such parentheses make life harder, not easier. § Nested comment starts This refers to two consecutive comment starts with no intervening comment end, eg ____ /*#define DEBUG /* some comment here */ ____ where the intent is to define or undefine DEBUG by removing or replacing the first comment start. If your code employs this (lazy) sort of construct, then instruct EnterAct that this is not an error by selecting Options… from the Edit menu and removing the check mark from the box titled “Detect nested comment starts”. There is an illustration of this in the “Options” chapter, by the way. As a side-effect, EnterAct will not be able to warn you if a comment end has accidentally been omitted. If you value the notion that EnterAct can fully trap any single failure to properly start or end a comment (something that many compilers, including THINK C, don’t do), then leave the check mark in the “Detect nested comment starts” box, and remove the nested comment starts from your code. Simplest, use "//" style comments instead. § Preprocessor tangles Although these do pop up, they're easy to fix up. Conditional #defines which duplicate important punctuation can cause trouble, such as ____ #ifdef GO_LONG long GetArrayIndex(void) { #else short GetArrayIndex(void) { #endif ____ —EnterAct will complain about the '{' being there twice, and the simple fix is to put the curly brace (which isn't conditional anyway) after the conditional part: ____ #ifdef GO_LONG long GetArrayIndex(void) #else short GetArrayIndex(void) #endif { ____ EnterAct's parser can sometimes spazz out because it's trying to handle C and C++ and first-draft code and all possible values of a #define all at once. For example, ____ typedef struct A #ifdef __cplusplus : public B #endif { ____ used to generate a complaint, and there may still be similar constructs out there that cause a problem. The fix is to provide the full C and C++ introductions separately, as in ____ #ifdef __cplusplus struct A : public B #else typedef struct A { ____ And one more tangle: if you put something that's deliberately uncompilable in your code, avoid all punctuation except commas and semicolons (some few others might work). For example, ____ #ifdef A_Compiler #ifdef B_Compiler error - won't you please make up your mind?! ... ____ would trip EnterAct, whereas ____ #ifdef A_Compiler #ifdef B_Compiler error, please make up your mind ____ while lacking punch, would work fine from EnterAct's view. § All–or–nothing macro’s This final restriction is one that you may run into, but the workaround is easy. An “all–or–nothing” macro is a macro that looks something like ____ #ifdef BLUETREECOMPILER #define P(x) x #else /* some other compiler */ #define P(x) #endif ____ —so P(x) either does nothing at all to its argument or it “eats” the argument, but either way the macro itself disappears from the code. If such a macro is the very first thing in a statement then EnterAct will deal with it correctly, for example "P(typedef int INT16;)" would result in INT16 being recorded as a typedef’d equivalent of “int”. However, if the all–or–nothing macro is not the very first thing in the statement, as in ____ int myFunc P((int x, long y)); ____ then EnterAct will mistakenly record “P” and not “myFunc” as the function name, and in general it will misrecord any similar statement where an–or–nothing–macro isn’t the first thing in the statement. In case you’re wondering, the intention of ____ int myFunc P((int x, long y)); is to produce either int myFunc (int x, long y); or int myFunc (); ____ —in other words either a proper modern prototype or an old–fashioned declaration, and this sort of thing is useful when writing code that will be compiled using different compilers. What to do? Call up the Macro's to skip dialog from the EnterAct menu, and enter the name of the macro there. (PLEASE NOTE you may not realize you have an all-or-nothing macro until after you have built your dictionary. If this is the case, you should completely rebuild your dictionary to ensure that all definitions are correct. To completely rebuild your dictionary: • hold down all three of the <Shift>, <Option>, and <Command> keys while using the mouse to select Update Dictionary from the EnterAct menu. ) (This button reads “New projects” if no project is open at the time.) - - - - - - - - - - - - Projects - - - - - - - - - - - - § Introduction Any collection of TEXT or PICT files from up to 6 disks can be added to an EnterAct project. The project window displays three lists of files in your project, and behind the scenes your project contains a dictionary of C/C++/Java term definitions, prototypes, and general notes. To create and make use of a project: • use New Project to create an entirely new project, or use Save As with a project window in front to build on an existing project • if you have nonstandard file extensions (beyond the usual .c, .h, .cp etc) use the "File Extensions..." dialog to make your project aware of them • add files to your project, the easiest way being to drag folders or files or aliases onto your project window (note there is no need to select a pane) • bring your dictionary up to date with Update Dictionary • pick AutoLook from the EnterAct menu • thereafter, bring your dictionary up to date whenever you want your dictionary to reflect new or altered definitions. • to switch to a different project that you've had open recently, <Option> or <Command> click in your current project window's title bar to pick from a popup list (please see "Switching to other projects" below -- <Option>clicking will close all your text windows, whereas <Command>clicking will not) • things work best if you include definitions for all the names in your source code, especially toolbox terms but also PowerPlant or TCL, and ANSI headers. NOTE if a folder's name is in parentheses, the files in it will not be added to your project. To exclude a folder such as "Old Source", change its name to "(Old Source)". The three lists of files in the project window can be used to open files, by double-clicking on the file names listed there. You can set up a multi-file selection by holding down the <Option> key and clicking on or dragging over file names, or select all files of a certain type by using the buttons in the Find dialog. Bullets (•) will appear beside selected files. This list of files can be used with multi-file searching or passed as input to a hAWK program or one of the “Index” commands under the EnterAct menu. You can also remove the selected files from the project with Remove •'d Files. To exclude a file from being built into your dictionary, hold down the <Command> key and click on its name (more on this later). Other things you can do with the lists of project files: • Find all or part of a file name (useful with enormous lists, have the project window in front and select the appropriate list before using Find or Find Again) • Copy a selected file name • use the up and down arrows to move up and down the file lists, and the left and right arrows to change panes • type your way to a particular file in a pane, by typing the first part or any distinctive part of the name (priority given in that order) • open a file by selecting it and issuing the “Go to” command The project window goes to the back whenever you open a file from it, and is listed under the Windows menu as the first file. Any project files that you have open when you close a project are remembered, and reopened as you left them when you reopen the project. The dictionary is required by regular lookup (click just after a term name and press the <Enter> key), and by the AutoLook window which displays definitions and prototypes automatically as you edit or mouse around. More on this later, of course. Only one project can be open at a time. You don’t need to have a project open to use EnterAct as an editor. § Project files An EnterAct project can track any set of TEXT or PICT files. The source and header files don’t have to add up to a compilable application—anywhere from one file to part or all of the source and documentation for several applications can be an EnterAct project. The only practical limit is available memory, since your entire dictionary is kept in memory: allow EnterAct 7 Meg if you can, otherwise you may have to delete some of the larger unneeded header files from your project. An EnterAct project can contain files from up to 6 disks. If your project files are split across several disks, you should have all the disks on–line (mounted) before updating your dictionary or doing things with a multi–file selection. EnterAct tracks your disks by name, and many other applications do the same, so please ensure that all your disks have different names. If you ever find it necessary to move a considerable number of files from one folder or disk to another, the simplest way to deal with the change in any EnterAct project that refers to those files is to throw the project away and create an new one. Or, you can use Remove •'d Files (<Option>drag over the file names first in the project window so that bullets (•) appear to the left of the names) followed by Add Files and then Update Dictionary afterwards to update your project. And a third way, slightly more complicated: • before moving the files, select all files for multi-file ops (call up the Find dialog and click "All") • run the hAWK program "$EchoFullPathNames", and use Save As to save the resulting list of full path names • move the files • edit the disk or folder names in your list of full path names to reflect the new locations • create a new EnterAct project, hold down the <Shift> key, and select Add Files from List… - double-click on the file you created that contains the full path names. (A fourth way to relocate files, activating the "Relocate files automatically" option in the Options dialog, works only if all your source and header files have unique names within the context of their disks, and works only if you change the folder where they reside - it doesn't work if you change disks. Use of this option is NOT recommended, unless you're quite sure that your files have unique names on their disks.) EnterAct can handle the following changes to file and folders without requiring you to make a new project: • renaming a folder • moving a folder around within one disk • moving a file to a different folder, provided the file name is unique on the disk, if you activate the "Relocate files automatically" option (see just above, not recommended for casual use) As mentioned, EnterAct cannot track files if you move them to a different disk, unless the two disks involved have the same name. Tip: if you often restore your project files from another disk, try using a smart copy utility such as CopyDoubler(tm) or equivalent: this will preserve all folders involved, and EnterAct won't lose track of any files due to two or more files having the same name. Second-best for this case, make aliases for all the source folders involved in your project, and place the aliases in your EnterAct folder. Then you can build a new project quickly after restoring your files, by dragging all the aliases at once onto your new project window. § Creating a project Select New Project from the EnterAct menu at any time. When you start EnterAct by double–clicking on its icon, you’ll see the New Project dialog if you cancel the Open Project dialog that appears first during the startup. Since the the project will always be saved for you automatically, there’s no such thing as an “Untitled” project: you’ll have to give it a home on your disk before doing anything with it. You can also use Save As to create a copy of an existing project. This is a quicker approach if you want a basic set of files to be added to a fresh project. To create a “starter” project, once you have a list of files in mind: • create a project that contains just the basic files, and give it a name that reflects its status as a “starter” • bring the dictionary up to date, so this only has to be done once for the basic files • set the font, size, and screen placement of the project window. Thereafter, to use a “starter” project as the basis of a new project: • open the starter project • immediately use Save As, and give it an appropriate name • proceed as with a new project, adding files and building the dictionary. Candidates for inclusion in a “starter” project include toolbox headers (omitting the ones you don’t need reduces memory needs) and the on-disk manuals supplied with EnterAct. If you’re an object-oriented sort, then many of the files in your class library of choice will qualify as well. § Selecting your <system> folder When you create a new project, a second dialog will appear asking you to select the folder to designate as the <system> folder: this is the folder where the "Add Mac Headers" command will search for your Mac headers ("Quickdraw.h and friends), and it is also the folder used to distinguish between All ".h" and All <.h> (or .c) in the Find dialog when you are selecting files to search. If you cancel the "Select <system> Folder" dialog when creating a project, the folder that contains EnterAct itself will be used by default. Rather than move EnterAct to your compiler's folder, life is simpler if you make an alias for the folder that holds your choice of toolbox headers, and put it in the folder where you will keep your EnterAct project (personally, I keep them all in my EnterAct Stuff folder). Then when you're asked to select a <system> folder, select the alias you made. You can use a folder that contains the toolbox headers, but things are easiest if the folder you use does not contain two different versions of the toolbox headers or some other important set of headers. You can change the designated <system> folder for a project at any time by using the "Select <system> Folder...." command under the EnterAct menu. § Three panes—.c, .h, plain text Any files you add to your project whose names end in .c, .C etc (source files) will be placed in the left pane. Header files (ending in .h, .H etc) will go in the middle pane, and any other TEXT files that you add will end up in the right pane. PICT’s will also be placed in the right pane. Here's a complete list of file extensions that are recognised by EnterAct: ____ c C h H cp cpp c++ asm CP CPP C++ ASM hp hpp HP HPP Cpp java Java jav Jav JAVA JAV ____ Of these, the ones starting with h or H are added to the middle pane, and all others are added to the leftmost pane. If you have special file extensions after a period, eg “.Proto”, that you would like to have treated as source or header files, see the “Custom file extensions” section a few pages on. The dictionary-builder does not look at files in the right pane, which is reserved for documentation. However, it will extract definitions and prototypes from all files in the left and middle panes. If you don't want a file in the left or middle pane to be parsed by the dictionary builder, hold down the <command> key and click on the file name in the project window to place a dash '-' beside it. In each pane, the files are sorted alphabetically by name. Since EnterAct is not a compiler, there’s no need to set up code segments. If you add more than one file with the same name, truncated full path names will be shown to the right of the names so that you can tell which one is which (usually). § Adding Java files Nearly everything for Java files is the same as for C++ files. For best results, find the source folder for the standard java libraries somewhere (eg CW9) and drag it onto your project. § Add Files—the one-at-a-time way The Add Files command will let you repeatedly add files (one at a time) to your project, until you cancel the dialog. The appropriate pane for each file will be chosen for you. The type of the file you add can be TEXT or PICT. § Adding files from a list The Add Files from List… command appears in place of the Add Files command when you hold down the <Shift> or <Option> key. A standard Open dialog will appear, in which you should select a text file that contains a list of full path names of files to be added to your project, one name per line. Within EnterAct, a list of full path names can be generated by selecting the desired files in your project for multi-file operations (hold down the <Option> key and click on the files in your project window), and then running the hAWK program $EchoFullPathNames. See the “Search” chapter for multi-file selections, and Appendix 2 for hAWK. Recommended, for VERY important projects take a minute to produce a list of all files in your project: • with the project open, call up Find and click the "All" button to place bullets beside all files (just make sure all disks for the files are mounted) • select "hAWK", pick the $EchoFullPathNames program from the top popup menu, and click "Run" • Save the resulting document as "MyProj Files" or equivalent. Later, if you need to recreate the project, you can do so quickly with the Add Files from List… command. However, these days it's simpler to create aliases for all the source folders involved in your project, so recreating the project just involves dragging the folder aliases onto a new project window. § Add All In Folder—the fast way To add all files in a folder to your project: • select Add All In Folder • select a folder that contains files to be added • click on the button with the folder's name at bottom • do another folder, or Cancel When you click the bottom button, all TEXT files in the folder will be added to your project. Files in subfolders will not be added. This command will also repeat until you click the Cancel button. As with Add Files, there’s no need to select a project pane beforehand. (Clicking on the "CEDARL_Source" button would add all files in that folder to the project, and also all files in subfolders if the <Shift> key was down while picking the "Add Files" menu item.) To add all files in all subfolders to your project as well, hold down the <Shift> or <Option> key while picking Add All In Subfolders (the key command won’t work with the <Option> key, just the <Shift> key). Then select a folder and click on the bottom button with its name. .Note that <Command><period> will interrupt this all-inclusive version of Add All In Folder, in case you start in the wrong place. This <shift> version of Add All is the exact equivalent of dragging a folder or folder alias onto your project window. You can also select and add individual files with the Add All command, but note this will have exactly the same effect as selecting the folder that contains the file, adding all files in the folder (and optionally subfolders). § Add Mac Headers The Add Mac Headers command will search the folder that contains EnterAct and all sub–folders for the file “Quickdraw.h”. Wherever it is found, all files in that folder will be added. If not found, you will see a message from EnterAct mentioning that “Quickdraw.h” wasn’t found anywhere. You can add these headers yourself with the Add All In Folder command. If you hold down the <Shift> or <Option> key while selecting this command, then in addition Add THINK Headers will also be done (see just below). If EnterAct complains that it can't find your toolbox files (or just as bad, that if found more than one version), you can add the toolbox files yourself--the easiest way is to make an alias for the toolbox headers you want, and place it in your EnterAct folder. Then you can add the headers by dragging the alias onto your project window. § Add THINK Headers This command will add all files in the folder containing “THINK.h” to your project. These include “asm.h”, “pascal.h”, “SANE.h” etc. If you're using CodeWarrior or MPW, this command doesn't do much. § Add Standard C Headers This command will add all files in the folder containing “stdio.h” to your project. § The active pane When you click in one of the three file lists it becomes the active pane, as indicated by highlighting of the file name you click on, and activation of the scroll bars for that pane. You can also switch between panes by using the left and right arrow keys. Some project-related commands such as Update Dictionary and Find In Next File are independent of the active pane, while others act within a particular pane. Here’s a list of commands and features which apply to the active pane: • the active pane is relevant only when the project window is in front, in which case one of the file names in the active pane will be highlighted, and the scroll bars will be active • to scroll the currently-selected file in the active pane into view, press <Enter> • as you drag about in the active pane the currently-selected file will change to keep up with your mouse, with full autoscrolling • to move up and down the list of files in the active pane, use the up and down arrows. <Option><up arrow> selects the first file in the pane, and <Option><down arrow> selects the last file • to change panes, click in the pane you want or use the <left arrow> and <right arrow> keys • type part of a file name to advance to a particular file in the active pane, eg type "mou" to advance to either "Mouse.h" or "MAIN_Mouse.h" -- a match on the first part of the name is tried first, and if that fails then a match anywhere within the name counts • Copy will copy the currently-selected file name in the active pane • double-clicking on a file name opens the file, and the currently-selected file in the active pane can be opened with the Go to command • the active pane is searchable with the Find and Find Again commands when the project window is in front, or just behind the Find dialog. Note that when the Find dialog is immediately in front of the project window the “Find” button will search the list of file names in the active pane, whereas the “Find In Next File” button will search through the contents of those files marked with bullets (•). Searching through the active pane for part of a file name or a file extension is handy when you have a great many files in a pane • Remove File removes the currently-selected file in the active pane from the project, deleting both the file name and the associated dictionary entries. § Remove File To remove one file from a project, bring the project window to the front, select the file by clicking on it, and then select Remove File. If you have built a dictionary for the project, the dictionary will be automatically updated for you. § Remove •'d Files The “•” refers to files in the project window that have been marked for multi–file operations (a bullet • appears to the left of the file name). Before issuing this command, first mark the files that you wish to remove with bullets (<Option>drag over the files in the project window). You can also mark all files of a particular type by using the buttons in the Find dialog. Any dictionary entries associated with the file will also be deleted. See the next chapter for a description of your project dictionary. By the way, this is the only command in EnterAct that will pay attention to bullets beside PICT file names. All other commands which deal will your list of bulleted files (such as Find In Next File, or passing the list as input to a hAWK program) will quietly ignore the PICT files, since all other multi-file commands deal only with text files. § Custom file extensions The File Extensions command under the EnterAct menu allows you to specify additional file extensions beyond the standard .c, .C, .h, .H etc. Type in your own extensions (up to 48 extensions, each up to 5 characters), and pick which pane the file should be added to. For example to have “.Proto” files added to the middle pane, type in “Proto” (don't type the period) in one of the extension fields and click the corresponding “Mid pane” button. Extensions are case-sensitive, so “PROTO” is not the same as “Proto”. If you have multiple versions of the same extension, you should enter them separately. If a project is open when you pick File Extensions the extensions you enter will apply to that project only, as indicated by the “This project” button. If no project is open at the time, the extensions will be used for any new project you create (the bottom-left button will read “New projects” in this case). Please note any file that is added to the left or middle panes will be parsed, and terms contained will be built into your dictionary, as explained in the next chapter on dictionaries. This means the files must be in C/C++/Java (or at least “C--”), otherwise the dictionary builder will complain. To get around this for an individual file, <command>click on the file name in the project window to place a dash '-' beside it. One use for this that you might like to explore later is creating your own “.Note” files. The “.Note” extension will remind you of their contents, namely hyperlinked notes on any subject that can be called up with a click and press of the <Enter> key. This is described at length in the “Lookup” chapter, which you’ll get to eventually if you just keep reading along. Here’s what the File Extensions dialog looks like: ("This project" reads "New projects" if you don't have a project open) § Distinguishing ".h" from <.h> The All ".h" and All <.h> buttons in the Find dialog let you set up a multi–file search for just one kind of header (ie system or your own), and since bullets • are shown beside selected files selecting one or the other kind will give you an on–screen way of telling which are which. Similarly, the All ".c" and All <.c> buttons allow you to select source files in either your project folder or your system folder for multi-file operations such as searching. The "system" folder is the one that contains EnterAct. Note for this to work properly you must select the appropriate <System> folder either when making the project or at any time thereafter using the "Select <system> folder..." command. Technically, the Find buttons mentioned above bullet files in the left or middle pane based soley on their disk location. In particular, any files with custom file extensions such as “PROTO” or “Notes” will end up with bullets if they they fall in the category selected (<.h> and <.c> for the <system> folder, ".h" and ".c" for elsewhere). § Copy and search in the project window When you have a file name selected in the project window, you can Copy it and then Paste it into a text window. This helps sometimes with documentation. With the project window in front, you can type as in a Finder window to advance the selection in the current project pane to the first file name that begins with the characters you typed. You can also type any unique part of a file name to select it, for example if you have the source pane selected and "NPXWE_DialogHandler.cp" is the only file name in the pane that contains "Dial", then typing "dial" will select that file. Neat! And, if you have an enormous project, the Find dialog will let you search for part or all of a file name in a particular pane. Select the pane in the project window that you wish to search, call up the Find dialog, and then continue as though you were searching for something in a text document. § Project memory needs EnterAct will be keeping your entire project dictionary in memory, for rapid access, and this does place a practical limit on the size of a project. Roughly, the memory needed will amount to 500K for basic operations plus 16% of the size of all source (left-pane) files plus 120% of the size of all header (middle-pane) files, with “size” meaning the size of a file’s data fork in bytes, rather than the disk space used. Note that toolbox and other header files can take a large memory bite, so if memory becomes tight your greatest savings can be realised by removing header files that you don’t really need built into your dictionary. As a rule of thumb, give a small project about 2 Meg to work with, and allow about 7 Meg for a larger one (say 1 Meg of source code with most toolbox headers). For more details, especially on toolbox headers and their memory needs, please see the document “EnterAct memory needs”. § Multi-file selection The general notion is to select one or more of the project files listed in your project window, and then issue a command that acts on all selected files. The classic use is for multi-file searching. To create a multi-file selection for your current project: • (Coarse tuning) in the Find dialog, click on the various buttons that select all files of a particular type • (Fine tuning) hold down the <Option> key and click on or drag over file names in the project window. This acts as a “toggle”, selecting files if they were not selected and vice versa. The cursor will change to an “eye” when it’s over the project window with the <Option> key down. Each file included in your multi-file selection will have a bullet (•) to the left of its name in the project window. Your multi-file selection can be used in the following ways: • to carry out a multi-file search; enter the text to be found in the Find dialog, and click the “Find In Next File” button there, or use the equivalent command under the Search menu. For more on this, see the “Search” chapter. • to remove files from your project; use the Remove •'d Files command described earlier in this chapter • as input to a hAWK program; for example, to generate a list of full path names for all text files in your multi-file selection: • select the hAWK command under the EnterAct menu • use the “Program:" popup menu to select “$EchoFullPathNames” • click the “Run” button, and wait a bit... the list of full path names will be shown to you in a fresh window. • as input for one of the “Index" commands, as described in the “‘Index’ commands” chapter. For more on hAWK see the “hAWK User’s Manual”. (Coarse-tune your multi-file selection with buttons in the Find dialog, fine-tune it by holding down the <Option> key and dragging over files in the project window) § Project context restoration When you close a project, or quit with a project open, the project will keep a list of all project documents that are open at the time. That’s your “context”. The next time you open the project, all of those project documents will also be reopened, and placed and scrolled much as you left them, and the Browser window will also be brought back if you left it open. This is all automatic, so in the rare event that you don’t want your context restored, do a Close All before closing the project or quitting. Some details: your windows will be put back exactly where you left them; file errors are suppressed during context restoration, so if a document seems to be missing try double–clicking on it in the project window; text documents will be restored with your insertion point or selection range scrolled into view, to avoid confusion; however, if a document is already open, only its window order will be restored; and if a document has been edited (anywhere) while the project was closed, it won’t be scrolled. Lookup windows and documents that haven’t been added to your project (including “Untitled” windows) are not restored. However, AutoLook will be restored. If you’re about to switch from one project to another, and want the project being closed to remember and restore the open documents, close the project before closing any of the documents that you want remembered—then open the other project. § Switching to other projects <Option> or <Command> click in the title bar of a project window to view a popup list of other projects that you have had open. When you pick one from the list, your current project will close and the one you picked will open. If you use the <Option> key, you will be asked to save any documents that need saving, and all text windows will be closed. If you use the <Command> key, all your text windows will be left open. Using the <Option> key to close all windows between switches is the better approach if all of the files you are dealing with are in your projects, since it keeps your screen from becoming buried under a sea of windows. § Tips When you double–click on a file name in the project window to open a file, the project window will at the same time move to the back behind all other windows. If the project window becomes hidden, you can bring it to the front again by selecting it from the Windows menu or using the menu key equivalent <Command><zero> which is always for the project window. Since the project window goes all the way front or back with a key–stroke or double–click, you can if you wish make the project window relatively large and treat it as a sort of backdrop mini–Finder If you begin the names of your own header files with a common character or group of characters, they will end up grouped together in the middle pane of your project window, and similarly for the other panes. Remember you don't have to type the prefix to select a file in the active pane, you just need to type some distinctive part of the name. If you're short on memory: To save on memory needed for dictionaries, create one or more “generic” projects which include header files that are often needed—and exclude headers than aren’t often needed. Select Update Dictionary before putting your generic project away. When you want to create a new project, open the appropriate generic one and use Save As to give it a new name. This way you won’t have to weed out unneeded headers to minimize memory needs, and your dictionary will already be up to date for the basic headers. - - - - - - - - - - - - Dictionaries - - - - - - - - - - - - § Introduction Once built, a project’s dictionary will contain entries for virtually every C/C++/Java term in every source (left pane) or header (middle pane) project file that is not restricted in scope to the body of a function. For functions and methods the dictionary entry will be the prototype or equivalent, and for all other terms the entry will consist of the entire statement in your source code in which the term was mentioned or defined. Regular use of Update Dictionary will keep your dictionary current as you develop your source code. As explained in the next chapter, the main point of having a dictionary is to give you instant displays of those definitions and prototypes. The AutoLook window shows them automatically as you edit, and more detailed and permanent displays can be generated by double-clicking on a name and pressing the <Enter> key. You can also jump to the definition of any dictionary entry, as explained in the “Seeing where a term is defined” chapter. The project dictionary forms the basis for the display in the Browser window. And there’s a hAWK built-in function that lets you determine the type of a C term within the context of your current project (see the hAWK program “$Whazzat”, which translates C declarations into English). The AutoLook window can also display definitions for local variables. For this to work, in addition to having a dictionary you should be working inside a function in a source file. § What’s in a dictionary After you’ve built your dictionary with the Update Dictionary command (see the next section), it will contain entries for everything of interest in your current project’s source (left pane) and header (middle pane) files that you would want to use in more than one function. Specifically there will be an entry for every: • function—all types including static, in–line, method • struct, union, enum, class • enum constant • #define—constant and macro • typedef • variable—all types including static, low–memory —provided only that the term is defined or mentioned outside of a function. Note that members of classes, structs and unions are included, as are prototypes or definitions of methods within class definitions. Local variables are not included in your dictionary, but the AutoLook window can look at your function to find the variable's defining type name (which should be a keyword or something in your dictionary). Dictionary entries for functions and methods will contain the prototype or equivalent. For all other kinds of terms, the dictionary entry will consist of the complete C statement in which the term occurs in your source code. All variants of a particular term will be included as separate entries in the dictionary. For example, if your source code contains the definition of a function and also a prototype for the function, then two entries for the function will be made in the dictionary. When EnterAct runs into conditional inclusion such as “#ifdef SomeThing ... #else ...#endif”, it picks up definitions in the first part and ignores the "else" or "elif" sections. The parser also ignores anything inside the standard “#if 0 ... #endif” construction. § Building your dictionary To exclude a file from being built into your dictionary, hold down the <Command> key and click on the file's name in the project window. The cursor will change to an 'X' while you do this, and a dash '-' will appear to the left of the file name to show that it is excluded. If you are adding files from a list (via <Shift>Add Files...), you can exclude a file from being built into the dictionary by placing an exclamation mark at the beginning of its path name, eg to exclude the file ____ HardDisk:Folder:src:George.cp ____ add a '!' so it reads ____ !HardDisk:Folder:src:George.cp ____ After you’ve added all your files to your project, select Update Dictionary from the EnterAct menu. If the dictionary–builder stumbles over a statement that’s too mangled to parse, you’ll see a message explaining in general what the problem is. You’ll also be shown the file in question, with the cursor placed at the position where the error was detected. Generally, most problems reported will be well–localised and fairly easy to fix—typical problems are lack of balance for critical delimiters, and missing or very badly spelled keywords. If you don’t see what the problem is, consult the “Dictionary build problems” section of the “If there’s a problem” chapter. EnterAct’s dictionary–builder will properly interpret a great many first–draft errors, including missing semi–colons, lack of balance in some delimiters (these vary according to context), slightly misspelled keywords, and some others. Your source code should mostly make sense, but it doesn't have to be perfect. In a contrary sort of way, using EnterAct will almost certainly reduce your first–draft errors. This is simply because you now have instant access to all spellings and types of struct members, all function and method calls, etc, so a major source of errors is now gone. § Keeping it up to date EnterAct does not update your dictionary automatically. Generally, you should select Update Dictionary whenever you change or add something that you’d like to have in the dictionary. Changes that take place entirely within the body of a function will not affect what’s in your dictionary. Any changes outside of a function body, including adding a new function, adding or changing an enum constant or struct or class member etc will be changes that you’d normally like to have reflected in your dictionary. Update Dictionary checks each file's modification time against the time it was last updated by Enteract, so there is no need to "make" an EnterAct project as a separate step. Update For Front File Only will rebuild only that part of your dictionary that is determined by the front text window. Unlike the other two update commands, this is a “manual override”, and rebuilds the dictionary for the front file whether or not it needs rebuilding. Normally you won’t need to use this command, because a full update with Update Dictionary for all changed files is almost always very quick. There are two special cases in which you’ll probably want to rebuild your entire dictionary: • enabling the “Detect nested comment start” option (see “Option” chapter), after having done a dictionary update with this option disabled • adding one or more new “macro’s to skip” (see the section on “All-or-nothing macro’s” in the “Source code restrictions chapter) To completely rebuild your dictionary, hold down all three of the <Shift>, <Option>, and <Command> keys while using the mouse to select Update Dictionary (note the key equivalent doesn’t work with this variation). A small point, but worth noting: if you make a significant change to a header file that’s #included in a great many source files, don’t be reluctant to bring your dictionary up to date. EnterAct’s dictionary builder only needs to scan changed files once, no matter how they are #included. The dictionary update will take just a few seconds at most (the tedious part, saving the new dictionary to disk, is done transparently while you continue to work). For example, on a relatively slow machine with a 68040 running at 25 Mhz, a typical incremental update will take 5-10 seconds. § How long will it take? Typically an update zips along at two to three files per second on a slow 68040 machine once it gets going. There is a bit of overhead at the end of an update while the browser is rebuilt, roughly three seconds. Project dictionary saving is done transparently in the background unless you close the project or Quit or issue some other command that requires a fully-saved project. You can go back to editing, looking things up, searching etc right after the last file is parsed. On a Quadra 840 or faster, update speed is simply astonishing. As mentioned above, all changed files including ".h" files are scanned only once during an update. Your regular dictionary update will probably involve no more than four files, and for this your total time "lost" will typically be under under six seconds. On a Quadra 840, blink and you miss it. If you need to interrupt the dictionary update, press <Command><period>. This also interrupts multi–file searches, and printing, and hAWK programs, by the way. You can finish the job off properly later by reselecting your original dictionary update command. § Show Dictionary (This command is not especially useful, since in practice most dictionaries are very big, and you'll run out of memory.) This command produces a “raw” dump of all the text in your dictionary, consisting of all the definitions or declarations that the dictionary–builder extracted from your code. At the top will be a comment listing the number of definitions of each type. The entries in the dictionary dump will be grouped together by file after a comment giving the file name, and within each file will appear in the same order as they occurred in the original file. You can use Save As if you wish to save your raw dictionary. - - - - - - - - - - - - Lookup - - - - - - - - - - - - You can expect that better than 90% of your routine information needs will be satisfied by the AutoLook window. For remaining needs, regular lookup (press <Enter>) pulls up definitions of terms to separate windows, and also works when your spelling is off but “distinctively close”. And reverse lookup (<Shift><Enter>) shows definitions of structs, unions, and typedefs that contain a particular member, again in a separate window. Please note that definitions of local variables appear only in the AutoLook window, and if you want them in a separate window you'll have to do the Copy-New-Paste thing. Lookup and many other features (such as jumping to a definition) are fully functional with first-draft code. All lookup windows, including AutoLook, are fully editable, but can't be saved. EnterAct's lookup features can be used to help out less "language aware" editors. If you feel more comfortable working that way, see the last section in this chapter (but read just below about <Enter> for lookup, <Shift><Enter> for member lookup, and the all-important AutoLook window first, please). § AutoLook The AutoLook command calls up an automatic lookup window which updates by itself to show dictionary entries as you type, edit, or click around with the mouse. It will instantly retrieve and display a definition for the words that lie just before your insertion point, or within your current selection (which can be part of a larger word). And it’s just as editable as a regular text window (Cut Copy Replace etc), though you can’t save changes to it. AutoLook is context-aware: it can determine if a name is a local variable, and when dealing with members or methods it tries its best to look in the appropriate inheritance chain. If you're in a plain document rather than a source file, AutoLook still works, but with less accuracy. AutoLook can be used to look up a simple name, such as "noErr": just click after the name and its definition will appear instantly in the AutoLook window (for this one, you'd need to add Mac Headers, or at least Types.h, to your project). And AutoLook can be used to resolve a complicated "reference chain". Taking a C example such as ____ mySFRPtr->sfFile.parID ____ if you clicked after "parID" you would see in AutoLook that it is a long member in an FSSpec; and if you clicked after "sfFile", AutoLook would show that it is the FSSpec member in a StandardFileReply struct. And if you clicked after "mySFRPtr" in the function where I took this example, you would see that it is a local variable of type "StandardFileReply *", together with the definition of a StandardFileReply. Actually, AutoLook is much easier to use than to describe--try it! Just click after any name of interest, anywhere. Summary: • AutoLook shows definitions instantly for terms to the left of your insertion point, or within your selection • If you're working inside a function in a source file, then the AutoLook window will also display definitions for local variables. • If you're working within a method, lookup shown for members and methods will be more accurate than if you're in a plain document • Your spelling must be exact for most terms - if you don't see what you expected, press the <Enter> key to look up a top-level term, or <Shift><Enter> to look up a struct or class member (see below) • AutoLook shows supporting definitions for a name when appropriate (eg if a name is a variable of type FSSpec, you'll also be shown the definition of an FSSpec). For another example, if there are entries in your current dictionary for “Window”, “WindowData”, and “WindowDataPtr”, then all three entries will appear in succesion in the AutoLook window as you type “WindowDataPtr”. Selecting “Ptr” will call up the definition of “Ptr”, whereas selecting (or clicking after) “contained within the WindowDataPtr” will call up the definition of “WindowDataPtr”. In both of these latter cases, the full definition of the "WindowData" struct will appear in the AutoLook window. If the definition of the word involves obvious typedefs, #defines, or structs or unions, definitions for them will be appended to the AutoLook display—for example, if you double-click on a global variable gEvtDetails you won’t see just "EventDetails gEvtDetails ;" you’ll also see what an EventDetails thing is defined to be. (as of v3.5, we skip the "middlemen", for example the typedef for "EventDetails" is not shown in AutoLook, since it adds little to comprehension) As mentioned, the AutoLook window produces fast accurate lookup for data members, when you're working in a method. Click after or double-click on the data member's name, as usual, and the declaration for the data member will appear in the AutoLook window, followed by any supporting definitions -- eg "Thing *dataMember;" would be followed by the definition of "Thing". The AutoLook window will tell you which class definition the declaration was found in, either the class that owns the method you're working in, or any of the classes it inherits from. This "data member" lookup for AutoLook is case-sensitive, and the beginning of the name you're looking up must match the beginning of the data member's name exactly, to speed things up and cut down on spurious matches. If you're not working in a method or your spelling is slightly off, AutoLook will still often take a stab at showing you a definition, but it may just be guessing. EnterAct's parser doesn't resolve overloaded method names, so you may see more definitions than you want when you look up such a name. § Regular lookup (press <Enter>) The AutoLook window changes as you work, doesn't always show all variants, and works only with correct spelling. To produce a more permanent display of a definition, or a display listing all variant definitions of a name, or to pull up a definition for a name when you’ve forgotten the correct spelling, press the <Enter> key. You can either double-click on the name or type it in or click just to the right of it, then press <Enter>. As a special case, note that local variables are not in your dictonary and so definitions for them will show only in the AutoLook window. This may change in a future version. Hey, the top of the function isn't that far away. To toggle between your working position and the top of a function, use the "Go Back" command, or mark both locations using the Locations menu. To produce a more permanent display of a local definition, you'll have to manually copy it to another window. Lookup windows also provide a context for jumping to one of several definitions for a term, as described in chapter 11, "Seeing where a term is defined." In brief, to jump to a specific definition for a term: • press <Enter> to look the term up to a separate lookup window • pick the one you want; either <Option>click in the lookup window's title bar, or keep pressing <Enter> • <Option>double-click on the term you want (for a two-part name such as "Class::method", do the double-click on one name and then drag to the other name before releasing the mouse). Back to pushing the <Enter> key: definitions that match or come closest to the term you’re looking up will be displayed in a new “lookup” window. It looks like a regular text window, but the title of the window will be the term you’re looking up, preceded by two bullets (••). Text in the window can be edited (Cut Copy Replace etc), but changes are temporary. In the display box along the bottom of the window you will see the name of the file from which the definition was taken, followed by a number such as “1/4” indicating that the definition is the first of four available in the window. This number can range from “1/1” to “1/60”. In all lookup windows, to view other definitions: • hold down the <Option> key (or the <Command> key) • click-and-drag in the lookup window’s title bar • select from the resulting popup menu describing the definitions. Or, press the <Enter> key to view the next available definition, <Option><Enter> to view the previous one. (Double-clicking on “KeyDetails” and pressing the <Enter> key produced the “••KeyDetails” lookup window. The cursor is caught in the act of an <Option>click in the title bar of the lookup window.) When your spelling is exact, the lookup window will contain all variant definitions of the term. For example, there will often be a defining instance and prototype for a function, and quite often a struct and a typedef with the same name will exist. Unlike AutoLook, regular lookup works even if your spelling is off. There are no arcane rules to memorize concerning what to type if you can’t remember the exact spelling of a term: just type your best guess. Do use the correct case though, because regular lookup is case-sensitive, the same as C itself. OK, regular lookup will compensate instantly for a single case error, but otherwise it will start looking for best matches through your whole dictionary, and this takes a moment. If your spelling was off, the lookup window will hold definitions for terms that best match what you typed, in order according to how well they match. In this case, you control how many matches are available in the lookup window (see “Number of entries per lookup” later in this chapter, it's a field in the Options dialog). When your spelling is incorrect, EnterAct first checks for common errors such as full spelling when an abbreviation is needed, use of a common synonym, permutations, and single case errors. Up to this point, regular lookup is instant. If no match is yet found, EnterAct then checks all entries in your dictionary and locates the ones that best match what you typed, based on runs of matching characters. This phase may take several seconds, but is still much faster and easier than searching through files yourself. Very much faster. As each definition appears in a lookup window, a selection is made for you. For functions, the function name and parameter list are selected, and for all other terms the name of the term itself is selected. Here’s a general example illustrating typical use of regular lookup: • you type the name of a function in one of your working windows, but the AutoLook window doesn’t change: this means your spelling was off • press the <Enter> key, and a lookup window appears, holding several definitions that come closest to your spelling • the first one shown isn’t the one you wanted: press <Enter> repeatedly to advance through the definitions. Normally the one you want will be among the first three. Or, hold down the <Option> or <Command> key and click-and-drag in the title bar to pick from a popup menu of alternates • viewing the function you want, use Paste Selection Behind to copy the function name and parameters which have been selected for you, return to your working window, and paste the function name (now correctly spelled) and parameter list over your guess—all in one step. § <Enter> for lookup, advancing, scrolling Pressing the <Enter> key in a normal text window means “look this up”, but in a lookup window it can also mean “advance to the next definition”. The different behavior corresponds to your intent. Here are the rules for <Enter> in a lookup window: • to look up a name shown in a lookup window definition, double-click on it or click after it or type it in and press <Enter>. This is the same as in a regular text window. • to cycle to the next definition; if you haven’t altered the default selection made for you in the lookup window, press <Enter>. If you have altered the selection, use Select All before pressing <Enter>. If your selection is so large that it couldn’t represent a word to be looked up, or if it agrees with the name of the definition already being shown in the lookup window, EnterAct will cycle you to the next definition. The same rules apply to <Option><Enter>, which takes you back to the preceding definition in a lookup window, but also does “sounds like” lookup as described as few sections ahead. By the way, using the <Enter> key to just scroll the top-left of your selection into view or to toggle between showing the top and bottom portion of a large selection still works, the same as in ordinary editors. Once again, it comes down to your intent: try the <Enter> key out to do lookup, advancing through definitions, and scrolling your selection and you should quickly find that you can treat it as a “Do What I Mean” button. On the rare occasion when it doesn't advance you to the next definition in a lookup window, whack it twice quickly. That'll teach it. § Looking up the clip (press <Command><Enter>) To look up the last word on the clipboard, hold down the <Command> key while pressing <Enter>. EnterAct’s private clipboard is updated when you switch in and out. So to look up a term encountered while using some other editor: • Copy just the term • switch to EnterAct (an appropriate project with built dictionary should be open) • hit <Command><Enter> A lookup window will appear after you press the <Enter> key, showing the dictionary entry that best matches what you typed, or those that come closest if your spelling erred, just as if you typed the word in a text window and pressed <Enter>. OR just leave your AutoLook window in front -- when you return to EnterAct, the AutoLook window will automatically display whatever info it can for the last word on the clipboard. This lets you use EnterAct as a high-speed lookup helper when you're working mainly with some other editor. Just arrange your windows so that you can see the AutoLook window when you're in the other editor, then having a definition in view is as easy as Copy, click on the AutoLook window, click on your other editor's window. § Reverse lookup (press <Shift><Enter>) To retrieve all struct, typedef, and union definitions that contain a word or phrase, select the word or phrase, or click after just a single word, and press <Shift><Enter>. Reverse lookup is not case-sensitive, but otherwise your spelling must be exact. It’s very fast, though not instant. Results are shown in a lookup window, and you can view the different definitions either by pressing <Enter> to advance to the next definition, <Option><Enter> to view the previous one, or by <Option>clicking in the lookup window’s title bar. Here’s the lookup window that results from typing "ioFDirIndex" and pressing <Shift><Enter>, with the dictionary containing most toolbox headers: (<Option>click in the title bar for the popup listing definitions in any lookup window. “iofdirindex” would work just as well as “ioFDirIndex”, and “ioFDir” would have produced similar results, perhaps with a few more definitions shown.) Reverse lookup works with a single word or a phrase up to 255 characters, and just looks for a match in struct, union and typedef definitions regardless of where the text occurs. The most common use is to look up a member name, but you can also use it to look up a distinctive word or phrase in a comment that you recall seeing, perhaps in one of your own “popup notes”, as described in “Looking up your notes” later in this chapter. As of version 3 of EnterAct, the text you're looking up must begin with the start of a word for reverse lookup, but need not end with a complete word. Tip: type the member name using proper case, and check the AutoLook window: it will show a list of all structs, classes, and unions that contain that member name. And in most cases you can press <enter> instead of <shift><enter> to produce a "reverse lookup" window. The only real exceptions are names that are #defined, such as #define STANDARD_FIRST_MEMBER long next; --in this case you would have to press <shift><enter> after typing STANDARD_FIRST_MEMBER if you wanted to see what structures made use of it, since pressing <enter> would just show you the definition of STANDARD_FIRST_MEMBER. But heck, only IBM and MicroSoft commit that sort of barbarism these days.... § “Sounds like” lookup (press <Option><Enter>) When you can’t remember what case conventions were used for a name, or your recollection of the spelling is very very vague, type in your best guess and try <Option><Enter> instead of just plain <Enter>. This activates “sounds like” or “phonetic” rather than regular lookup. Upper and lower case are treated as the same, vowels are used to determine what the surrounding consonants sound like, and consonants are converted to standard phonetic equivalents in your guess. This “boiled down” version of your guess is then compared with similarly boiled-down versions of all names in your dictionary, and you will be shown the definitions of the ones that come closest in the resulting lookup window. The different definitions available can be viewed in the same way as with regular lookup windows: use <Enter> and <Option><Enter> to cycle forwards and back, or <Option>click in the title bar and choose from the popup menu. Sounds-like lookup should be kept in mind as an “emergency backup”, worth trying if regular lookup doesn’t bring up the definition you want As an example, suppose you’re after the definition of ParamBlockHeader, but misremember it as PARAMHEAD. Regular plain-<Enter> lookup would fail in this case, since it is case-sensitive. Pressing <Option><Enter> would work, but might also call up spurious matches (who knows what, perhaps kPrimeHidden) since it largely ignores vowels. On the other hand, if you misremember CopyFile as KoppeePheill then sounds-like lookup will work, and I imagine you won’t be complaining about the few extra spurious matches that it throws up. § Viewing other entries in lookup windows <Enter> and <Option><Enter> take you forwards and backwards through the different definitions available in any lookup window, as described in the section “<Enter> for lookup, advancing, scrolling” a couple of pages back. For a quick overview of all entries in the lookup window, hold down the <Option> or <Command> key and click (and drag) in the lookup window’s title bar. A popup menu will appear, listing the first line from each entry (or at least a good part of it), and you can go to the entry by selecting it from the menu. The first letter in each menu item indicates the type of the entry ('v’ for variable, ‘(’ for function, ‘#’ for define etc). For details, see “Hints with lookup” below. (<Option>click-and-drag in the title bar) § For faster lookup If lookup on average takes longer than you’re willing to wait when your spelling is off, the simplest cure is to trim unneeded files from your project, thus reducing the size of your dictionary. See “Project memory needs” in the “Projects” chapter for a guide to trimming files, and also the document “EnterAct memory needs”. Regular lookup for exact spelling is always instant, and reverse lookup nearly so. § Hints with lookup (Optional reading, for diehard powerusers) When you type in a name and press <Enter>, you know what “kind of thing” you want, but EnterAct doesn’t. Supplying EnterAct with a quick hint will help speed up the lookup if your spelling doesn’t match an entry, and it will in all cases limit the entries that are retrieved to the type that you specify with the hint. A hint for lookup consists of one character added after the name you wish looked up. Normally you’ll need to first type a space and then the one–character hint, to separate it from the name. However, the hint for a function “(” and the hint for a #define “#” can’t be part of any name, so the space is optional for these two. Here are the hints you can supply, with examples: in all cases you should select an insertion point just to the right of the hint just before pressing <Enter> so that EnterAct can pick up the hint correctly, or select the word and the hint. For all except the function and #define hints, a bit of space (blanks or tabs) between the name and the hint is necessary. ____ Type Hint Example ---- ---- ------- function, method ( SomeFunc( struct, class s MyStruct s variable v globalVar7 v #define # BIGNUM# union u IntOrFloat u enum e ErrorCodes e enum constant c eNoMemory c typedef t MyStruct t ____ In the display box of a lookup window you will see one of the above hints for each entry, between the file name and the current entry number. This is just to remind you that EnterAct keeps track of what kind of thing each term is, and that it will understand the above hints if you supply them. When should you supply a hint? Almost never. Perhaps when you have a struct, a typedef, and a variable that have very similar names, you don’t remember the exact spelling, and you want just one of them without the nuisance of the others. Since flipping through lookup entries is as fast as pressing the <Enter> key once the lookup appears, the only common reason to supply a hint is to speed up the lookup process itself. But in this case you should first try trimming unnecessary files from your project, as this will also speed things up by reducing the size of your dictionary. § Number of lookup windows With too many lookup windows on–screen at once, your screen will be too cluttered. If too few are available, that will hamper you when you have a complicated problem to wrestle with. The upshot is that the maximum number of lookup windows on–screen at once must be under your control, so you can vary this number as the situation demands. You can change this number at any time by typing a new number in the “Number of lookup windows” box in the Options dialog. The default number is 4, but you can vary it from 1 to 10. The “Number of lookup windows” includes any that you mark for keeping around, and determines when a lookup window that is not marked for keeping around will go away on its own. When you press <Enter> to see a new lookup and the lookup window limit has already been reached, one of the old lookup windows that was not marked for keeping around will quietly go away, and the new one will replace it. There’s no predicting which one, so if you want a lookup window to stay up until you explicitly close it, select Keep Lookup Around while it is the front window ( see “Keeping lookups around” below for details). § Number of entries per lookup When your spelling doesn‘t match any term in your dictionary exactly, the number of entries that are retrieved in the lookup window is under your control. To change this number, select Options and type a new number in the “Number of entries per lookup window” box (see illustration just above). The default of 4 suits most cases, but you may prefer 3 or 5. The maximum of 20 entries is useful only when your recollection of the correct spelling has gone right out the window. § Keeping lookups around The command for this is under the Windows menu. When you select Keep Lookup Around with a lookup window in front, the lookup will be marked for keeping around, which is to say it won’t close unless you close it yourself. Other lookups not marked for keeping around may quietly close when you ask for a new lookup after having hit the limit on the number of lookup windows on–screen at one time. When you select Keep Lookup Around for a lookup window, the beginning of the window title will change from •• to ¶¶ to show you that it is marked for keeping. A ¶ is a Paragraph mark, which starts with P, and that stands for Permanent. A lookup window marked for keeping will close only if you select Close or Close All, or close the project, or leave EnterAct. In other words, it’s as permanent as a regular text window. Since the AutoLook window changes so often, if you want to preserve an entry you should look it up in the usual way, by double-clicking on or clicking just to the right of the word (or partial word) and pressing the <Enter> key. You can do the lookup right in the AutoLook window if you wish. After you’ve used the AutoLook window for a bit, it serves as a spelling checker for terms. If you don’t detect a slight flicker in the AutoLook window out of the corner of your eye when you type the name of a term that should be in your dictionary, take a glance at the AutoLook window—if the definition or prototype isn’t there, you have a spelling error. § Looking up your notes Here’s how to build your own hard–won notes and observations about programming the Macintosh into your dictionary, for quick retrieval by name. You might call them “popup” notes, but as you’ll see, they’re just a variation on looking up C terms and the notes appear in the AutoLook window or a regular lookup window. Note files consist of fake C constructs, the sole content of each construct being a comment which contains the specific note. Suppose, for example, one of your notes concerns the modification date (“modDate”) for a file. To be able to retrieve the note, you first need to think of a memorable name for it, such as “modDateNote”. Then, in your note file, you would set up the dictionary entry like this: ____ struct modDateNote { /* Paste the note in here, within a comment that makes up the entire "struct" body. */ }; ____ The note goes inside a comment, which makes up the body of a struct. Placing the note inside a comment is necessary, to prevent the dictionary builder from trying to interpret your text as C code. There are other constructs you can use, such as ____ #define modDateNote /* Paste the note in here, within a comment that makes up the entire "define" body. */ or int modDateNote /* your note here in a comment */; ____ but a struct is definitely the best, since reverse lookup can then be used to retrieve a note based on some distinctive word or phrase that it contains. Since notes are always placed inside C comments, you should avoid C comment starts and ends (/* and */) within the note itself. It remains only to persuade EnterAct to build such a file into your dictionary. EnterAct will do so for files that are in the left or middle pane of your project, and by default if a file name ends in “.c” or “.h” etc it is added to the left or middle pane respectively. However, a slightly nicer approach is to give your note files an ending that describes what they are. A reasonable choice would be “Notes”, and then your note files would have names like “File.Notes”, “Memory.Notes”, “Interface.Notes”. To instruct EnterAct that files with names ending in “Notes” should go in the left or middle pane, select the File Extensions command and type in the file extension (eg “Notes”) that you choose for your note files—see the “Custom file extensions” section in the “Projects” chapter for an example. Which pane these files go in (left or middle) is up to you. Using a custom extension rather than the default “.c” or “.h” for your note files will also help prevent confusion if other people examine your work. Now add the note files to your project, select Update Dictionary, and you can retrieve any note to the AutoLook window by typing its name in any text window, and pressing <Enter> will place the note in a separate new lookup window. If the name of the note consists of the exact topic followed by “Note” then it will be easy to remember. And if you place a comment in your source code containing the name of the note, such as /* see modDateNote */ then all you have to do is double-click on the note name (and press <Enter> if you want a more permanent view than the one shown in the AutoLook window). A note can be of any length, and if you edit it heavily you can probably clean up the appearance afterwards with Reformat Selection. For an example of a note file, see the file “hAWK_notes.h” on disk 2. As a specific example, ____ if ((**availRgn).rgnSize > 10) /* see RegionNote */ { yPos = 5; y = *(((int *)(*availRgn)) + yPos); while (y != 32767) { xPos = yPos + 1; ...etc ____ might look like Greek to me if I come back to review it, but by clicking to the right of RegionNote in the comment and pressing <Enter> I can view my hard–won note on regions that explains in more detail what’s going on: Often it’s simpler to just place a “go to” link in your code (consisting of a file name followed by a marker name, as detailed in the “‘Go’ commands” chapter). “Go to” links have two advantages over popup notes: any text in any document, including support documents, can be marked for use a link, and the text at the link can include illustrations. But “popup” notes as described above have two advantages over “go to” links: they appear in politely placed and sized windows, as do all lookup windows, and you can view several notes from the same file in separate windows. A mix of “Go to” links to access existing or complex documents, and popup notes to retrieve details on specific programming tasks might be best. § EnterAct as a "definition finder" for other editors To use EnterAct as a "definition finder" with other editors: • read enough here to learn how to create a project, build a dictionary, and show the "AutoLook" window. Knowing how to call up "lookup" windows by pressing the <Enter> key is also useful. That's all above here. • when you're using the other editor, also run an EnterAct project with contents roughly corresponding to the code you're working on - have the "AutoLook" window open, as the frontmost text window in EnterAct. Your project dictionary should be reasonably up to date. • to look up a term with EnterAct; Copy it in the other editor, and switch to EnterAct. If you don't immediately see the definition in the AutoLook window (rare), press <Command><Enter>. To look up the class or struct that contains a particular member, press <Shift><Command><Enter>. § Looking it up with THINK Reference or Toolbox Assistant You'll see "Find in THINK Reference" and "Find in Toolbox Assistant" under EnterAct's Search menu: to get them working, create a folder named "Tools" or "(Tools)" next to EnterAct at the same level, and drop aliases of THINK Reference and QuickView into it. When you want to look something up, either select a term or click just after it and issue the appropriate menu command (the command key equivalents <Command><-> and <Command><4> are worth memorizing). - - - - - - - - - - - - Seeing where a term is defined - - - - - - - - - - - - § <Option>double–click To see the file in which any dictionary term is defined, hold down the <Option> key while double–clicking on the term. EnterAct will enter the term in the Find dialog (the equivalent of Enter Selection), open the file where the term is defined, and scroll to the first instance of the term in the file. Except for functions, methods, structs, classes, unions, and enums, for which you’ll almost always be scrolled to the exact defining instance, with no tripping over a mention in a comment or variable declaration or prototype. (Note you can look up the definition of a full method name, in the format "class_name::method_name", by <Option>double-clicking on the class name, dragging over to the method name to select it as well, and then releasing the mouse. Or if you prefer you can look it up by selecting both names and then using the Find Definition command.) Here's an example of looking up a class definition: (those are old-style window, but the idea is the same....) If you are viewing just a method name, without the class name: • bring up your AutoLook window (you'll find it's useful all the time) • click after or double-click on the method name in your source window • AutoLook will show a complete list of prototypes for the method name • select the one you want, class name and method name inclusive, in the AutoLook window and use Find Definition • or <Option>double-click on the class name, drag to the method name, and release the mouse For example, to view the definition of "DoSpecificCommand" in the class "TFaxPage", when viewing just "someObject->DoSpecificCommand(1,2)", you would click just after "DoSpecificCommand" to see the following in the AutoLook window: ____ OSErr TFaxDocument :: DoSpecificCommand (short stdCommandNumber, long misc) OSErr TFaxEdit :: DoSpecificCommand (short stdCommandNumber, long misc) OSErr TFaxPage :: DoSpecificCommand (short stdCommandNumber, long misc) ____ --then select "TFaxPage :: DoSpecificCommand", and use the Find Definition command to jump to the definition. Or <Option> double-click on one of the words, drag to the other, and release the mouse. If your spelling of the method name is off, and nothing shows in the AutoLook window, click just after your guess at the name and press <Enter>. If your guess was close enough, the resulting lookup window will hold entries for all methods with the correct name. Hold down the <Option> key and click in the title bar of the lookup window to view a list of the methods -- if you see the right one, select it, and your desired one will appear in the body of the lookup window, where you can <Option>double-click or use Find Definition. § Find Definition Find Definition is useful with parts of a word (such as just the WindowData part of WindowDataPtr )—just select the exact term you want to view the defining instance of, without regard for what comes before or after it. Find Definition ignores trailing spaces or tabs, and also accepts hint characters in much the way that lookup does. § If there are multiple definitions If you have several methods with the same name, use the AutoLook window to pick the right one as described just above. In the general case, you can jump to a particular definition of a term as follows: • select the term or click after it, and press <Enter> to look it up • in the resulting lookup window, hold down the <Option> key and click in the window's title bar to view a popup menu listing all the definitions and abbreviated full path names for their locations • pick the one you want, then <Option>double-click on the term as shown in the lookup window. If the term is a static function or variable and you happen to be viewing the file where it is defined, then <Option>double-clicking on the name anywhere in that file will take you to the definition in that same file. Note if you want a list of all definitions of a term, the simplest way is still to do a Batch Find, then trim the results. § Other ways of finding definitions The AutoLook window will display definitions instantly when you select or click after a term, greatly reducing the need to “find” definitions. It will also show most class method definitions, and definitions for data members (these details are subject to last-minute improvements). And of course you can retrieve the definition of a term to a separate lookup window by clicking after the term and pressing the <Enter> key. “Go to” links, as explained in the “‘Go’ command” chapter, can be used to jump to any marked location in any file. This includes function and method definitions if you are using Automark to mark your source files in the default way. The "Cross-Reference" index command (chapter 22) can generate a cross-reference of C (only) terms in your source code that is compatible with EnterAct’s "Go to" command. These “file-name line-number” references can go out of date if you edit your files, but are handy for files that don’t change often. - - - - - - - - - - - - Browsing - - - - - - - - - - - - § The Browse command The window produced by this command shows a “family tree” of the classes in your project, as of your last dictionary update, and also allows you to quickly view any class or method definition. It will close when you close your project, and will update automatically when you update your project dictionary. In the browser, "user"-defined class names are underlined, whereas <system>-defined classes are not. The solid black horizontal and vertical lines connect each child to the first of its parents. If a class inherits from multiple parents, light colored lines connect the middle of each parent to the left or right end of each child. For example, given ____ class A : B, C, D {... ____ you would find in the browser window a set of solid horizontal and vertical lines connecting A to B, and light colored lines would connect the middles of C and D to the left or right end of A. If a class contains other classes or structs as members, they will be listed beneath the class name, separated from it by a white line. To view the definition of a class, double–click on the class name. This works much like <Option>double-click or Find Definition in a text window. This works with both a "main" class name and any of its member class or struct names. To view a method definition, click and hold on the owning class name: after a brief pause (your double–click time, actually) a popup menu will appear listing all of the class’s methods. You should then select the method you want and release the mouse button, as if you hadn’t guessed. This also works with member class names (as of this writing, it's untested with member struct names.) To view a popup of all methods in a class AND all methods that it inherits, hold down the <Command> key and click and hold on the class name. This list can be quite long, and may take several seconds to generate--please be patient the first few times you try it. Inherited private methods are not shown, and virtual methods are indicated with a "v" before the name. If your family tree of classes involves a great deal of multiple inheritance, the many light colored lines may become too tangled to decipher, and even obscure class names. To display just the colored inheritance lines for one class, click once on the class name (all colored lines not connecting to the class will disappear). To add lines for other classes, click on the class names with the <Shift> key held down. Similarly, you can suppress the colored lines for one class by <Shift>clicking on it. To show all colored lines again, click once on the white background between classes. Double-clicking to show a class definition does not suppress any colored lines, and neither does the click-and-hold to view a method popup. Instead of trying to follow the colored lines, you can view the parents of a main class by holding down the <Option> key and clicking on its name to view a popup of mom and pop etc. Note that releasing the mouse over one of the parents will take you to its definition, a feature I included mainly because a popup is supposed to do something. Classes without proper parents (orphans, if you like) will always appear in the left–most column of your browser window. A quick look down the left column will reveal whether you have any unintentional orphans, perhaps due to misspelling the parent class name in the class definition. (Note EnterAct works fine with CodeWarrior etc classes, for which there may be many base classes in the leftmost column.) § Finding classes in the Browser window To bring a particular class into view, type the first part or some distinctive part of its name. The name will flash once. You can also use the Find dialog and the Find Again command to find classes in the browser window (eg if you're looking at the source for a class and want to see where the class is in the browser, use Enter Selection to enter the class name in the Find dialog, then bring the browser to the front and do a Find Again). § Method and class popups (This is a summary of popups, as described above) • to view the methods associated with a class, click and hold on the class name. • to view all inherited methods as well, hold down the <Command> key while you click and hold on the class name. If the list is gigantic, it may take several seconds to generate the popup, so please be patient the first few times you try this. • to view a list of the immediate parents of a class, hold down the <Option> key while you click and hold on the class name. § Browsing classes without the browser Nothing new to seeing class definitions—click to the right of the class name and press <Enter>, or just look in the AutoLook window. You will typically find the class name of an object as the first name in the statement where it is defined, as in ____ TClassName *objectName; ____ You can also, of course, look up a class by typing the name and pressing <Enter>, and in all cases your spelling just needs to be reasonably close, not exact. In either case, the definition will appear in the AutoLook window if you have it open. § Browsing methods without the browser (The approach below is for use when your spelling of a method name is incorrect, or the owning class is determined at runtime. If your spelling is correct or the class is "fixed", you will see the appropriate prototype in the AutoLook window when you click after or double-click on the method name. To go to the definition, select the full "class_name::method_name" in the AutoLook window, then use the Find Definition command, or <Option>double-click, dragging to select both names before releasing the mouse.) Method browsing is a bit trickier, since if you have something like ____ "currentObject->Draw();" ____ and there are several different classes with Draw() methods, then EnterAct does not know specifically which Draw() method you want. If there is only one method in your project with a given name, then the lookup window will contain just one entry, but if there are several then the lookup window will contain all of them (up to a maximum of 60). For example, if you were to press <Enter> with an insertion point to the right of Draw above, then the lookup window might contain entries for void Circle::Draw(), void Square:: Draw(), void Oval::Draw() and so on. When there are several entries like this, you can cycle through them by pressing the <Enter> key, and back up by pressing <Option><Enter>. There are some illustrations of this just ahead. This raises the question of how to find where a method is defined. The general approach is described in the chapter “Seeing where a term is defined”, but the approach for a method has one extra step: • double-click on the method name, and a list of all methods with that name will appear in the AutoLook window; or, press <Enter> and cycle through the lookup window until you find the method you want, based on the name of the owning class • then select the entire name, consisting of the owning class name, the two colons, and the method name, in general className::methodName • and then select Find Definition. • (or <Option>double-click, ya ya you know already) There is one exception to this: if there is only one method in your project with the name in question, then a standard <Option> double–click on just the method name will jump you to the file where that method is defined. However, if there are several methods with the same name in different classes, there’s no predicting which definition you will see if you just <Option> double–click on the method name—best to look up the method first, and use Find Definition on the full name of the exact one you want. By the way, when viewing the full “className:: methodName” of a method, you can look up the definition of the owning class of the method by clicking at the right end of the class name, before the colons, and pressing <Enter>. If the instance of the method name you’re viewing doesn’t have the class name attached, look up the method name as decribed just above to see the full method name including the owning class, and then do your lookup for the class in the lookup window shown for the method. If you want to see where a method is defined, but can’t remember the exact spelling of the name, type your best guess and press <Enter>. The true name you wanted will probably be among the first few entries in the lookup window, and then you can proceed with an <Option> double–click or Find Definition right in the lookup window to get to the file you want to see. If you want lookup for a method when you’re not sure of the spelling, and want to restrict the lookup to just methods, type a bit of the class name and two colons just before the method name—even C::method will do (even if the class name doesn’t contain a “C”—it’s the two colons which signal that a method is wanted). EnterAct is not a fancy bells–and–whistles browser, but it does allow you to look everything up quickly. And, it has two advantages over any other browser: your code doesn’t have to be perfectly compilable, just reasonably close; and your spelling when you want lookup for anything (including methods and classes) doesn’t have to be perfect, just close enough to be distinctive. Try that on your SmallTalk! A method-browsing example: Here we've typed "EstablishPort" in a new window, and then pressed the <enter> key: the corresponding lookup window holds entries for all EstablishPort methods. The cursor is caught in the act of <option>clicking in the title bar of the lookup window to select the entry for LOffscreenView::EstablishPort. After the LOffscreenView::EstablishPort appears in the lookup window, <option>double-clicking on it takes us to its definition. - - - - - - - - - - - - Documents and windows - - - - - - - - - - - - § New, Open, Close New under the File menu means a new text window. To create a project, select New Project from the EnterAct menu. A new lookup window appears automatically whenever you look something up. New PICT windows can’t be had, no matter what you try. Open under the file menu allows you to open any TEXT or PICT document. To open a project, select Open Project from the EnterAct menu. Close will close the front window, whatever it is, and the key equivalent <Command><W> is often handy. Close Project will close the project window whether it is in front or not. Only one project can be open at a time, so if you select Open Project while a project is open you will be asked to confirm putting away the current project. The same applies if you select New Project. To close all text windows, select Close All from the Windows menu. This will not close your project or the Find dialog. EnterAct provides some support for unix and DOS files. Specifically, you can open, change, and save them, and change from one type to the other using the little popup menu at bottom-left of the windows. § Save, Save As, Revert Save applies only to proper text documents (not lookup windows) and to PICT’s. Saving a PICT will alter only the window location that EnterAct saves with any file. To save the contents of a lookup window, Copy what you want and Paste it into a regular text window. Projects are saved automatically, when you update the dictionary, add files, or close the project. Save As can be used with text and PICT documents, and with a project as well. In particular, you can set up a project to use as “stationery”, with the font and window location preset, and commonly needed files already added—for details see the “Projects” chapter, section “Creating a project”. Revert applies to text and PICT documents only (with PICT’s only the position on your screen is reverted). § Close and Save Documents These two new commands are under the Windows menu, supplementing the old Close All and Save All. The Close Documents and Save Documents commands affect only windows which already have a corresponding file on disk: in particular, “untitled” windows are left alone. By contrast, Close All also closes lookup windows and asks you to save any “untitled” windows—and Save All also asks you about saving “untitled” windows. § Autorevert When you select Autorevert for an open document, EnterAct will check the disk file for the document every 10 seconds, and refresh the document’s window if the contents of the file have changed. This continues until you select Autorevert for the document again (it’s a toggle) or until you close the window. To remind you that the document’s window is being autoreverted, a “disk-to-window” icon will be shown in the window’s display box. Typically EnterAct will not detect that a file has been changed until it is closed by the program that is changing it. While implemented in a general way, Autorevert is primarily meant for use with hAWK programs that print ongoing progress messages to disk. Several of the supplied hAWK programs print messages to the file “$tempProgress”, and by monitoring this file via Autorevert you can watch how programs are progressing as they run. For more on this use of Autorevert see Appendix 2. Every decent app needs one nutty gizmo. Hence Autorevert. § Modify Read Only EnterAct watches out for Projector 'ckid' resources, and won't let you change a file if it has been checked out of SourceServer as "read only". When a document can't be changed for this reason, a small pencil with a slash through it will be shown in the display box of its window. When you need to edit a file that has been checked out as "read only", select "Modify Read Only" from the File menu. This makes the file fully editable, and alters the 'ckid' resource slightly so that SourceServer will know the file has been changed when you check it back in. "Editable" meaning you can change the text in the window and save the changes, just as with a regular document. No icon is displayed for "modifiable read only" files, mainly because your author can't figure out what the heck that means. Whatever else it does, it severely compromises version control. If you want to ignore 'ckid' read-only stuff altogether because it doesn't apply to you, deselect the "Ignore 'ckid's" option in the Options dialog (see illustration just below). § Saving window locations Saving window locations is nice, provided you aren’t pestered all the time to save your changed location when you close a window. In EnterAct, saving window locations takes the place of neatly tiling and stacking windows. By default, EnterAct will save window locations whenever you save a text or PICT document. If you would rather not have window locations saved, call up the Options dialog and uncheck the “Save document window locations” item. Any saved locations will also be ignored when a document is opened if you uncheck this item. § ... without being pestered Beneath the “Save document window locations” item in the Options dialog there’s another check box, “...but don’t pester me about saving locations”. Both of these options are on by default. The “don’t pester” part means that you will not be asked if you wish to save a text window when you close it if all you’ve done is change the window’s location on the screen. The location of the project window is always saved (this is automatic) regardless of your options. § Newly opened windows can be long or short If the “Save document window locations” item in the Options dialog has a check mark, and if a document you open has a window location saved with it, then EnterAct will restore your document to its saved location. Otherwise, EnterAct won’t have a remembered location for the window, or will ignore it (this is especially true of a new text window). You can roughly control the length of these windows with the radio button options “Windows open short / long by default” in the Options dialog. Long windows will reach all the way to the bottom of your main screen when they open. Short windows will indeed be relatively short on a large screen, but will fill most of a small screen. The default is short windows. Note that you can grow just the length of any text window down to the bottom of the screen by holding down the <Option> key while clicking in the zoom box. And it won't cover up your AutoLook window. The default width of a new window is fixed at a moderate size, about 74 characters in Monaco 9 (this is also a near–maximum nice width for printing). For existing documents, the width will be based on the first 20 lines of the text, within reasonable limits. Note that if a document is being opened during restoration of a project’s context its location will be where you last left it, not necessarily the same as where you last saved it. § <Option>–Zoom zooms just the length If you hold down the <Option> key while clicking in the zoom box of a window, only the length will be affected. If you’re zooming out (the first zoom is usually an “out”), the bottom of the window will drop down to the bottom of your screen, rather in the way a menu drops down. Zooming in is not affected by the <Option> key. The window you're zooming will stop short of covering your AutoLook window if it's in the way. § Number of windows at one time Restrictions on the maximum number of windows on–screen at one time are as follows: ____ regular text, PICT memory-limited lookup 10 or fewer (see below) project, Browser, AutoLook, Find - one of each at a time. ____ Note you can print any number of EnterAct text files by selecting them in the Finder and then selecting the Finder’s print command, since the files will be opened, printed, and closed one at a time. While the hard upper limit on lookup windows is 10, you can set the maximum number on–screen to any number between 1 and 10 using the Options dialog. The default number is 4. § The Windows menu Consisting of: Close All, Close Documents, Save All, Save Documents, Keep Lookup Around, and a list of your open windows, with the project first and others in order from front to back on your screen. Close All affects text, lookup, and PICT windows. If it needs saving, you’ll be asked. Lookup windows will be quietly closed, since they cannot be saved. The combination of Close All with remembered window locations lets you arrange groups of documents to work with at one time, and switch between groups with a minimum of nuisance. Save All will save any text or PICT documents that need it (note lookup windows aren’t saveable). If a text window hasn’t been saved yet, you’ll see the standard Save As dialog. If you use MultiFinder or System 7, and you decide to switch off the “Safe switching under MultiFinder” option in the Options dialog, I would strongly recommend that you use Save All or preferably Close All before switching to another application. Close Documents and Save Documents do the same as the Close and Save All versions, but affect only documents, ie windows that correspond to an existing disk file. Keep Lookup Around applies only to lookup windows. The maximum number of lookup windows on–screen is fixed (although you can change this number at any time in the Options dialog), and when this limit is reached the next lookup window that you call up will quietly close one of the old lookup windows to make room. To avoid having a particular lookup window disappear later on you, select Keep Lookup Around when the lookup window is in front. The two bullets •• at the beginning of the lookup window’s title will change to ¶¶, showing that it won’t go away until you yourself close it. Note especially that Close All will close all lookup windows, whether or not they are marked for keeping. To bring a window to the front, select it by name from the lower part of the Windows menu. If a project is open, it can always be brought to the front with the menu key–equivalent <Command><zero>, which is worth memorising. No other windows (except dialogs) have key equivalents—if your memory is that good then in my humble opinion you don’t need EnterAct in the first place. § The display box All text windows including lookup windows have a small “display box” along the bottom in the horizontal scroll bar area. For a regular text file this displays the name of the file; in a lookup window it shows the name of the file from which the entry was taken, followed by the (abbreviated) type of entry, the number of the current entry shown, and the total number of entries available in the lookup window. When you drag the mouse to select text in a text window, the display box will change to show the line number that the mouse is currently on, followed by the number of characters selected. If more than one line is selected, the display box will show the number of lines selected rather than the current line number. To determine how many lines there are in a file, use <Option><down arrow> or Go Bottom and click on the last line of the file. To determine the number of characters in a file, click at one end of the file and then <Shift>click at the other end of the file. A selection on one line, line number displayed: A selection on several lines, number of selected lines displayed: The little popup with "M" in it at bottom-left of the window allows you to change the file format: (as of v3.7.8 there is a command to turn coloring on and off in the little popup as well). § Printing To print a text file, bring its window to the front and select Print. A Page Setup beforehand will be needed if you wish to print in a nonstandard way, such as sideways or with an unusual paper size. To stop a printout, press <Command><period>. Printing of PICT’s or other kinds of files is not supported, just text. However, any illustrations in a text document (see next section) will print properly, with automatic nudging to avoid clipping a picture off at the bottom of a page. EnterAct does not clip long lines of text, but folds the “hangover” back to the left margin on a new line. The line-break is not always as good as you yourself would do it, but at least you will never lose any characters off the right edge when printing. - - - - - - - - - - - - Editing - - - - - - - - - - - - § Introduction EnterAct provides all the standard text editing commands, which should be familiar from elsewhere (THINK C, for example), and so the emphasis in this chapter will be on EnterAct’s editing enhancements. Briefly, they are: • everything that changes a document is undoable one way or another, except Revert. In addition to the usual Undo/Redo under the Edit menu, you can also undo any one of your most-recent thousand activities, and limited file reversion is also available (see the “Show Activities” chapter) • "code templates": type a template name, press <command><return>, and it expands into the full "template", which can be any old chunk of text. And <command><return> advances you through the template • Paste Selection Behind combines Copy, switch to the next window, and Paste in one command • the indentation of your code will commonly be preserved when you Paste or Paste Selection Behind • the selection in the next–to–front window is shown in a frame, useful with the Paste Selection Behind and Find commands • Reformat Selection can “pretty up” a comment or selection of text, rebreaking lines to your specified width. • Syntax coloring, for line comments, strings, and ticks • Graphic nesting display • full Drag and Drop for text • you can paste and delete PICTs in text documents, see "Illustrating your text" near the end of this chapter. “Balance”, “Show Activities”, and “Options”, under the Edit menu, are described in their own separate chapters later in this manual. § Undo EnterAct has one level of undo and redo, via Undo/Redo under the Edit menu. The undoable and redoable actions are: typing, Cut, Copy, Paste, Paste Selection Behind, Clear (Backspace), Shift Left, Shift Right, Reformat Selection, Replace, Replace and Find Again, Replace All, and Drag and Drop. Revert is not undoable, though discarded changes can often be recovered with Show Activities. All other “undoable” changes (such as changing the font) can be undone by reusing the same command (such as changing the font back). Just clicking the mouse or selecting a range of text does not affect undo. Changing the window does make the last change temporarily undoable, but you can restore the ability to undo the last change by bringing the appropriate window to the front again. To selectively undo past activities or revert files back past the last saved version, see the “Show Activities” chapter. For these purposes, EnterAct records your last 10,240 activities in full to disk. § Typing, Cut, Copy, Clear “Typing” means hitting a sequence of keys that produces text, intermingled with any number of <Backspace>’s. A new typing operation begins whenever you change the insertion point or select characters and then type something. As with all actions, just changing the insertion point or selecting characters does not affect your ability to undo—it’s the subsequent change to your text that does it. When you type <Return> the resulting new line will have the same indentation as the line above it, unless you hold down the <Option> key, in which case you’ll end up flush at the left margin. Cut and Copy are as you would expect, but there is one special feature: if you want to take a screen-shot in EnterAct, first Copy a single character, and then immediately after taking the screen-shot paste it into your scrapbook. As an aside, please see "EnterAct's magic clipboard" for a way to run hAWK programs on whatever you Copy with EnterAct. The basic sequence is: you write the hAWK program you need, and start it running; and then whenever you need the program's results, Copy some text to give it the appropriate input, and Paste the results. Typically the menu bar will flash to show that your program has done something with the current clipboard's contents (this and all other aspects of the program are under your control). This effectively gives you programmable Copy/Paste using what has been called the best little language in the world, and some example programs are provided to get you going. "Clear" has the same effect as the <Clear> key, and <Backspace> is also the equivalent of a Clear if a range of text is selected. If no text is selected, <Backspace> will delete one character, whereas Clear will not. § Paste preserves indentation At least, it does if the range of text you select to be pasted over, or the insertion point for the paste, satisfies the requirement: “all tabs or spaces to the left at the start”. Also, the text must have been cut or copied with EnterAct. “All tabs or spaces to the left at the start” means that the first character you select for replacement should be the first character on the line that is not a space or tab. If you have just an insertion point for the Paste, then the same applies—there should be nothing but spaces and tabs from the insertion point to the left margin. Starting at the left margin will also do. The basic rule is you shouldn’t “see” any printing characters between the left margin and the start of your selection or insertion point. If this rule is satisfied when you are about to Paste, then the paste will preserve your relative indentation, removing the need to Shift Left or Shift Right afterwards. About the only special action you should take to have Paste preserve your indentation is to open up a new line with a <Return> just before you paste in a block of code, which you probably do anyway. A selection with all tabs/spaces to the left at the start: The cursor positioned on a blank line, tabbed in the appropriate amount, just before pasting in the above selection: After the paste (no shifting needed): Paste Selection Behind also preserves indentation. And so does Drag and Drop, if the drag starts within EnterAct. § Drag and Drop for text Dragging and dropping text is almost entirely standard in EnterAct, and all you need to know about D&D is: • you drag text around by making a selection and then dragging (mouse-down on the selected text, then move the mouse with the button still down). As you drag about, a cursor will move with you showing exactly where the drop will take place if you let go of the mouse button • when you drag text within its source window, you are "moving" it, ie it will be deleted from its original location and inserted where you see the cursor flashing as you move about • to duplicate rather than move the text when you're still in the source window, hold down the <option> key as you start or end the drag • if you drag the text to a different window, the original text in your source window will not be affected ever • I lied, if you drag the text to the trash it will be deleted from your source window • if the D&D starts and ends within EnterAct, your indentation will be preserved • to cancel a drag, release the mouse when it's over the top part of the title bar or over the original selection when you're still in the source window, or over the title or scroll bars when you're over some other window; or for that matter let go when you're in the menu bar at top of the screen • all Drag & Drops of text (even to the trash) are undoable. As you drag about in the source window, you can persuade EnterAct to scroll the text in the window by moving your mouse to the edges of the window (scroll bars, and small margins at the top and left). Inactive windows, in accordance with Apple's guidelines, do not scroll the text automatically as you drag around in them. Unless or course you want them to: in which case open the Options dialog, click on the "Edit" pane, and check the box called "Autoscroll inactive windows when dragging". This applies only if the drag starts in EnterAct. DON"T get too used to this, or you might forget that it violates the guidelines! Cancelling a drag is slightly harder due to autoscrolling, but the drag does cancel if you let go of the mouse while autoscrolling. § Code templates Save those fingers. All templates are stored in the text file "EnterAct Code Templates", which is very easy to modify (please take a look at it). Add this file to the folder where you keep EnterAct, at the same level. If you save changes to your "EnterAct Code Templates" file using EnterAct, your new templates are instantly available (no need to quit and restart). To use a template, you type its name and press <command><return>. And <command><return> will also advance you to the next logical insertion point in your template (or in any code for that matter). Templates don't have to contain code, and template names can contain any non-blank characters, not just letters and numbers. To force <command><return> advancing to stop at a particular point, put an '@' sign in the template. Then <command><return> will stop at the '@' sign and select it. There's an example just below. (For templates that contain C/C++/Java code, <command><return> will advance to almost all logical insertion points, with no need for '@' signs in the template. But feel free to put them in anywhere.) Keep all your entries flush-left, and EnterAct will adjust your indentation when pasting your template in. Just open up a new line and tab in to the right position before typing the entry name and pressing <command><return>. Here are two templates, from the "EnterAct Code Templates" file: ____ ENTRY for for (; ; ) { } END ENTRY i #include "@.h" END ____ Each entry begins with "ENTRY" on a separate line, followed by the name of the entry on a separate line, then the body of the template definition, and finally "END" on a separate line. To use the "for" template, you would type "for" and then press <command><return>. That would paste in the body of the template, and advance your insertion point to just before the first ';'. Every subsequent press of <command><return> would advance you to the next logical insertion point in the template. In the "i" (for "include") template, typing "i" plus <command><return> would replace the "i" with ____ #include "@.h" [plus a new line] ____ and select the '@' sign so you could type in a file name. You can use templates to hold arbitrary chunks of text. For example, if you find yourself typing "if (theErr == noErr) {}" a lot, you could reduce this to "e" plus <command><return> with a template entry such as ____ ENTRY e if (theErr == noErr) { } END ____ Tip: add "EnterAct Code Templates" to your "Locations" menu so you can change your templates on the fly. Remember, when you change your "EnterAct Code Templates" with EnterAct the updated templates are instantly available. hAWK command lines are handled specially: if your template name expands into a hAWK command line, it will all be selected, and if you press <command><return> a second time, Enteract will run the specified hAWK program. Here's a sample hAWK command line entry from the code templates file: ____ ENTRY echo hAWK -f$EchoFullPathNames -- MFS END ____ EnterAct treats any selection beginning with "hAWK" as a hAWK command line. If you type "echo" in a text window and then press <command><return>, then "hAWK -f$EchoFullPathNames -- MFS" will be pasted in as usual for a code template, but because it's a hAWK template, the entire line will be selected. The special symbol "MFS" stands for all files in your multi-file selection in your current project (the files with bullets on their left in the project window). So to run this program for real you should first select some file for multi-file operations in a project (see the Search chapter) and then type "echo<command><return><command> <return>". You will end up with a list of full path names for your selected files in the "stdout" window. § Selection: front, non–front EnterAct uses your chosen highlight color to show the selection in a text or project window when it is in front. In text windows that are not in front, the selection is framed with a black box. With Drag and Drop enabled (which it is by default), you can drag any selection around, or make a copy within the same window by holding down the <option> key as you drag. The selection in the second-front text window is not shown differently from other non-front windows, but this is the selection that will be affected by the Paste Selection Behind command (described in the next section), and it also shows where your search will start from when the Find dialog is in front of your text window. § Paste Selection Behind Paste Selection Behind does the following three actions in one : Copy what is selected in the front window; switch to the window just behind it; and Paste the copy in over the selection in that window. You’ll see your selection in the next–to–front window just beforehand, as described above. If you can’t see what is selected in the next–to–front window, you can either trust to memory (it’s undoable) or do a “manual” Copy, switch windows, Paste. Paste Selection Behind is especially handy when switching back and forth between your working text window and a lookup window, but it can be used with any two text windows. Your indentation will be preserved with Paste Selection Behind under the same circumstances that apply to a Paste (see “Paste preserves indentation” above). If you want to undo a Paste Selection Behind but have switched to a different window, bring the two windows involved in the Paste Selection Behind to the front alternately until Undo becomes enabled. The two windows involved are the one you pasted into, and the one you copied from. (before Paste Selection Behind: I typed "PutResInfo", but nothing showed up in the AutoLook window so I pressed <enter> to produce the "••PutResInfo" lookup window--WriteResInfo is what I wanted) (after Paste Selection Behind) § Font, font size, tabs Sizes for your font are restricted to sizes that are actually installed in your system. The default font for text windows in EnterAct is Monaco 9, with 4 spaces per tab. You can also change the font for the project window. The default here is also Monaco 9. For projects only, holding down the <Option> key while changing the font or size will give you a bold style. Tabs in EnterAct are of the relative sort, meaning that when you press <Tab> your insertion point advances to the next tab stop. Tab stops are placed a fixed number of spaces apart, and you can change this number with the Tabs dialog. Note that if you change the font it may throw off your nicely–aligned code, so it’s best to pick one font for code at the beginning of your programming career and stick with it. § Shift Left / Right Shift Left and Shift Right will shift one or more entire lines left or right by a tab stop, allowing you to repair or alter the relative indentation of your code or text. For simplicity, you should select one or more entire lines before calling these commands. They are undoable. (the effect of Shift Left on the above selection) § Reformat Selection Reformat Selection will rebreak the lines in your selection, but the result may not always be an improvement. It is designed to work with multiple paragraphs, provided you don’t indent the beginning of the first line, and that you separate paragraphs with a blank line. (the above after Reformat Selection, with the default settings) Reformat Selection doesn’t work well on C code, although it may on occasion help to tidy up a complicated “if” statement. It works best with one or more paragraphs of text, either an entire comment or part of a comment, or paragraphs in a text document. Since Reformat Selection is undoable there’s no harm in trying it. The maximum selection that can be reformatted at one time is roughly the standard Text Edit limit, 32,000 or so characters. The specific reformatting that Reformat Selection does is governed by the two "Reformat" options in the Options dialog. The default action is to rebreak lines with a “ragged right” format and a maximum line length of 74 characters, a nice width for printing Monaco 9. In the Options dialog (near the bottom) you can alter the maximum number of characters per line, and also select a “full justification” look if you want to knock people over with your comments. The maximum number of characters per line is restricted to a range of 30 to 150. § Syntax coloring Color can be applied to comments, strings, and constants inside ticks -- if you don’t like the default colors, there are a few commands to change them, under the Edit menu. This is a simple implementation of coloring. The goal here was to color only those things that might usefully be colored, things that don’t immediately catch the eye and yet are of some importance. Keywords are not colored; if they don’t immediately catch your eye yet, just be patient, with a bit more programming under your belt they will. Syntax coloring might improve with future versions, but one thing you can say about EnterAct’s coloring: it doesn't flicker! If you grow bored with merely colored comments, try out the "Comment options..." command under the Edit menu. § Graphic nesting display Hold down the <Option> AND <Command> keys with a source file frontmost and vertical lines will appear showing the scope of each statement block (ie anything inside {} curly braces). It’s OK to scroll with these keys down, but you should release them before further editing (I think). § Arrow keys for moving around The up down left right arrow keys will move your cursor by one character or line. If you hold down the <Option> or <Command> key an arrow key will take you all the way in the appropriate direction. <command><up arrow> and <command><down arrow> are especially useful for taking you to the top or bottom of your document. § Illustrating your text As you can see from this manual, there is a way to put PICT's in a text document. You can place dialog and screen snapshots, structure mockups, flowcharts, state machines, in short, any old PICT, into your spec, design, and test documents, even into your code files (EnterAct’s style of illustration goes unnoticed by compilers, PROVIDED you place the picture inside a /*comment*/). EnterAct's illustration capabilities are two in number: paste, by dragging a PICT in from another application; and delete, by "swiping" a PICT. Both of these are undoable. To Paste a PICT into a document: drag & drop it from another application (such as the Scrapbook). Note EnterAct cannot serve as the source for your PICT, only as the destination. To delete a PICT: "swipe" a small text selection within the PICT, to produce a dialog that asks if you want to delete the PICT: click OK. "Swipe"? That means do a fast mouse-down drag mouse-up. Beat your double-click time while selecting a blank line or three. Or if you prefer something more elegant, you can click on one line within the PICT and then <shift>click at your leisure on a different line. Pasting and deletion of PICTs are undoable operations. For a Paste, the undo item will refer to a Drag&Drop Paste, and for a delete of a PICT the undo menu item refers to a "Clear". PICTs are not recorded in your activity log. If you really need persistent undo for PICTs, please contact your author at the address at top of this manual. Be persuasive, because it wouldn't be easy. The position of each PICT is marked in the text by a <return><option-space> pair, and "blank" space is opened up for the PICT with a series of <return>s. Pasting or deleting a PICT makes a permanent change to the resource fork of your document (where the PICTs are kept) but the inserted text for the PICT position is not saved for you. To avoid surprises, Save after every Paste or delete of a picture. You can Paste up to 400 PICTs into one EnterAct document. PICTs can also be manually inserted by using a combination of a resource editor and text editing, as explained next. However, using EnterAct's Paste is far more convenient. (PLEASE NOTE the following "manual" approach is no longer practical, and is preserved here for information purposes only. This is because EnterAct now always renumbers your PICTs when you use the above paste/delete approach, and uses the sequence 1,000, 1,001...1,400 without any gaps. This is "Teach Text" compatible, but makes any manual insertion of PICTs impossibly tedious. You win some, you lose some.) Illustrations come in two parts: PICT resources, placed in the resource fork of your document using ResEdit or equivalent; and “picture markers” in the text of your document, each consisting of a <Return> followed immediately by an <Option><space>. If you have more than one illustration in a document, the PICT’s should be given ID numbers in the same sequence as they are to appear in your document. The numbers should be between 128 and 32,767, and if you anticipate coming back later to insert new pictures between old ones you should space the numbers out a bit, using for example the sequence 1,000, 1,100, 1,200.... All PICT’s should be made purgeable, as EnterAct does not insist on keeping the PICT’s in memory. In ResEdit, you can mark the PICT as purgeable at the same time as you set the ID number, using “Get Info...” with the PICT selected. For each PICT you wish displayed, you’ll need a <Return> <Option><space> pair at the position where you wish the illustration to appear. The simplest approach is to first use ResEdit to install your PICT’s in the document, then open the document using EnterAct and insert an <Option><space> at the beginning of the line where you want the first picture to appear. As you type the <Option><space>, the picture will begin to appear—you should then type enough <Return>’s to open up blank lines for the picture to occupy, so that it doesn’t overlap any following text (however, you may certainly overlap picture and text if you want). If you need to see the picture fully redrawn while doing this, click in the up or down arrow of the vertical scroll bar. Repeat for any following pictures. To sum up, the PICT’s in the resource fork of your document should have ID numbers that are in the same order as you want them displayed; for each picture there should be a <Return> <Option><space> followed by enough blank lines to make room for the picture. To insert a PICT between two existing PICT’s, give it an ID number between the numbers for the flanking PICT’s when you paste it in with ResEdit, and put the “picture marker” of course between the flanking markers. Note that if you add PICTs using a resource editor and then later use EnterAct to Paste a PICT into the same document, your PICTs will be renumbered automatically using the sequence 1,001, 1,001, 1,002... up to 1,400 without gaps. If your pictures end up displayed in the wrong order, you can be sure that their ID numbers are not in the correct order. A missing picture means that either the PICT or the <Return> <Option><space> for it is missing. A picture can be moved around between two flanking pictures just by cutting and pasting the picture marker, but to change the order of pictures you will have to change the PICT ID numbers to the sequence you want. Excess PICT’s won’t be displayed until you enter a picture marker, and excess markers don’t hurt, but may be triggered unexpectedly if you add a PICT at the end of your file. A file with two PICT illustrations that have been pasted in using ResEdit: The "Activities" PICT in "EnterAct Log": the small black rectangle is the <Option><space> that marks the picture insert position (shown selected). Several <Return>'s follow, to open up enough room for the picture. For a whopping big example, examine this document and its resources. - - - - - - - - - - - - Balance - - - - - - - - - - - - NOTE you can also Balance a delimiter by double-clicking on it. § Checks everything ...except those angular brackets that you find only in ____ #include <SystemHeader.h>. ____ The full list is (), [], {}, /* */, " ", and ' '. Balance will also detect nested comments and any single improperly–formed comment start or end. Two improper comment delimiters in a row (improper start followed by improper end, or vice versa) will not be detected, but that’s a one–in–a–million case that you’ll probably never see. Because Balance detects nested comments, it will signal an error if you use a comment start or end within a comment (nested comment starts are excepted if you deselect the “Detect nested comment starts” option in the Options dialog)—see “Nested and bad comments” below. For strings in double quotes " ", the line continuation character '\' must be the last character on the line if the string is continued to the next line: ____ "This string is \<Return> properly continued." "This string will trigger<Return> a Balance error." "So will \<space><Return> this string, due to the space before Return." ____ Balance will behave in different ways depending on where you are in the code. To Balance an entire file, select an insertion point at the very top of the file (<Option><up arrow> will take you there). To Balance a specific delimiter, either click just to the left of it or select the delimiter (note for comment starts and ends this means both characters). Given an insertion point, Balance will first look to the immediate right for a delimiter that wants balancing, and then to the immediate left. When several delimiters are side by side, you can avoid having to remember this by just selecting the delimiter you wish balanced. Clicking between the characters of a comment start or end also counts as a “hint” to find the other end. If your range of characters selected doesn’t consist of just a single delimiter, or if your insertion point is not right next to a delimiter, then Balance will try to find the smallest enclosing pair of delimiters. Your selection range will expand to the next enclosing pair as you repeat the Balance command. § Shows the error location Any unmatched or mismatched delimiter will be selected and shown. In the case of mismatched delimiters, you can switch between the two delimiters by selecting Balance again. If the delimiter is an “orphan”, the second Balance will just produce a beep, since there’s no other end to show. (if there’s a mismatch, a second Balance will show the other end) § Balancing a file Given an insertion point at the top of a file, Balance will balance the entire file. If you hear a beep and the cursor does not move from the top of the file, that means the entire file is balanced. Either Go Top or <Option><up arrow> will take you to the top of a file. Balancing a file by starting from the top will always work correctly. You can also Balance a file by starting at the very bottom, but this may not work properly if the file contains any assembly–language sections (see “The asm problem” at the end of this chapter). § Balancing a specific delimiter Balance looks for a “hint” from you, as indicated by your insertion point or selection, before going ahead. As mentioned above, you can Balance one specific delimiter by selecting it just before the balance, or by selecting an insertion point just to the left of it. If the delimiter is not next to another delimiter, you can click on either side of it. With comments and strings it is best to start the Balance off with a “hint”, that is, select one end of the comment or string or click next to one end, since if you start in the middle of a comment or string the text will be checked as strictly as possible, without allowance for it being within a comment or string. (Balance will take the selected ')' as a hint) § Nested and bad comments Balance will detect all nested comments, and any comment that has one end missing. In the case of a comment with one end missing , you will be shown a “good” end in the vicinity of the bad one, and you’ll have to deduce on your own where the other end should be. Comment errors can sometimes be subtle and difficult to see, such as a space between the '*' and the '/'. (The first comment shown here is not ended properly. Balance detects the start of the second comment as an attempt to nest comments, and shows it as an error.) (An immediate second Balance will show that the lower comment is correct, implying that the error was in the comment just above.) If you leave the “Detect nested comment starts” check box checked in the Options dialog, then any files in your EnterAct project are guaranteed to be free of these comment errors after a successful Update Dictionary, since the dictionary–builder checks comments thoroughly. The one price to be paid for EnterAct’s improved comment checking is that you should not use a comment start or end within a comment. Such things as /*.../*...*/ and /*...*/...*/ will be treated as errors, both by the Balance command and by the dictionary–builder. If you do need to use a comment start or end within a comment, the general cure is to place some character between the star and the slash. A space will do, or you could be pedantic and place each character in separate single quotes, for example instead of /* use / * or '/''*'. Well, OK—some of you deliberately double up your comment starts to save on typing. If you do this, select the Options command under the Edit menu and uncheck the “Detect nested comment starts” check box. This affects the dictionary builder also. § Starting in the middle If your selection doesn’t indicate a hint, Balance first looks backwards in your file for a delimiter; when it finds one, it then looks forwards for another delimiter, hoping to match them up. Of course, if you supply an opening delimiter as a “hint”, or start from the top of the file, Balance will proceed in the forward direction immediately. On rare occasions you may wish to balance the contents of a comment or string as though it were code, and not just text. To do this, click or select a range of characters within the comment or string, away from either end. Balance will then check all delimiters as it works outwards, until it encounters one end of the comment or string and “realizes” that it has been fooled. By the way, EnterAct also accepts “C++” style comments, as in ____ //comment beginning with two slashes, to end of line ____ but only to the extent of skipping over the contents when balancing. If you start the Balance within this sort of comment it may just beep at you. Before Balancing: After the first Balance: After a second Balance: § The asm problem If Balance runs into an “asm {...}” construction while looking backwards through your code, it just plain won’t know that it’s inside an asm. Any error you’re shown in this one circumstance is not to be trusted, since it will almost certainly be due to a delimiter inside an assembly–language comment (they start with a semicolon). When you balance a file from the top, all asm constructions will be handled properly. The dictionary–builder, by the way, also handles asm’s properly. Be warned that in other cases if you ask Balance to run backwards through a block of assembly language it will hiccup if it runs into a delimiter within an assembly–language comment. This is a bug, but I haven’t found a cure that wouldn’t slow balancing down to a crawl. Because of this problem it is best to always balance an entire file by starting from the top rather than from the bottom, unless you’re sure that the file contains no assembly language. To Balance an assembly–language block, or a function containing assembly language, select or click next to the opening curly brace '{' at the top rather than the closing curly brace. Otherwise, this will only be a problem if you’re balancing inside a function that contains a block of assembly language. Then, you should select opening delimiters rather than closing delimiters before balancing. - - - - - - - - - - - - Search - - - - - - - - - - - - (both Find and Replace strings are limited to 255 characters) § Introduction Single and multi–file searches in EnterAct are controlled by a modeless Find dialog. The one important novelty is that you fine–tune your multi–file selection by holding down the <Option> key and dragging over the files in the project window (bullets • appear beside each file included in the search). Your multi-file selection can also be used to remove files from a project, or used by a hAWK program as a list of files to take input from. Replace, Replace and Find Again, and Replace All are all undoable. The commands Find, Find Again, and Enter Selection all function when the project window is in front, and the “find” commands also function when the project window is just behind the Find dialog. Find commands will search the currently active pane, useful if you are trying to spot one file in a long list, or pick out files with similar names. Enter Selection will enter the currently-selected file name in the Find dialog. § Find is modeless This requires a few minor adjustments in the way you search. There is no Cancel button in the Find dialog box—it has a Close box instead. While the Find dialog is the front window, search commands that deal with single files will apply to the window just beneath the Find dialog. Replace All is excepted because it can cause multiple changes, so to use this command you must have the text window in front. Find and Find Again also function if the Find dialog is in front of the project window, searching the current pane as though it were a text list of file names (actually, that’s what it is…). The “Find” button is the equivalent of the Find Again command. When you click the Find button or select Find Again, the window just beneath the Find dialog will be brought to the front, and the next instance of your find string shown. The Find dialog will stay on–screen, moving just behind the window being searched, so to find again you can if you wish leave your mouse stationed over the Find button and double–click (not a true double–click, the first click brings the Find dialog to the front, and the second does the Find Again). Buttons for multi–file searching are incorporated directly in the Find dialog (more on this in “Multi-file searches” below). To modify your multi–file search selection of files, hold down the <Option> key and drag over the file names in the project window. You’ll see the “eyeball” cursor while doing this. § Find options Select “Match Words” if you don’t wish to match a longer string that contains your find string in a form that makes a different word. For example, the string “Open” will also match “Opening”, “Opened” etc unless you select the “Match Words” option in the Find dialog. A special case: if your string begins or ends with punctuation, such as “->structMember” then leave “Match Words” unselected. “Wrap Around” will continue your search from the beginning of your document if the next Find runs off the bottom end of it. This also affects the Replace commands: to Replace All instances in a file, it’s simplest to select an insertion point at the top of the file beforehand; to Replace All instances below a certain point, click just before the position where you want the replacing to start, and leave “Wrap Around” deselected. “Ignore Case” treats upper and lower–case letters as the same. § Batch Find options If you click the "Batch" check box, your multi-file search will be done all at once, and the results presented in a text window (file name, line number, and the full line where found). To view a particular found instance in the original file, click on the result line and use "Go to...". For Batch finds, if you select "List markers" then the line that lists a particular location will include the containing function name. Here's an example result (results appear in the stdout window): ____ Batch find results for: «nextName» -------------------------------------------- «CEDAR_AutoLook.c» 3513 |ResolveOneLink| Boolean ResolveOneLink(StringPtr t1, short nextName, Handle *hTextP, long *primaryLinkP) «CEDAR_AutoLook.c» 3524 |ResolveOneLink| // Note nameLink0 is set only if nextName == 0. «CEDAR_AutoLook.c» 3841 |GetSomeTypeNameForMember| /* typeLink1 is the index of a type name, nextName is sNameChain index «CEDAR_AutoLook.c» 3843 |GetSomeTypeNameForMember| for nextName (and if nextName is 0 set nameLink0), return TRUE; ____ Once again, to jump to a particular instance, click on the line that contains the file location and use "Go to...". Please see "§ Skip '-' : excluding files from a search" below if you wish to skip certain files easily while searching or carrying out some other multi-file operation. § Dual Batch Find Translated into English, the dialog that appears when you click the Dual Batch Find button in the Find dialog lets you do "Find two strings wihin a certain number of lines or characters of each other". This is a multi-file operation, that is it looks in files that you've bulleted for multi-file searches, and it's a Batch operation in that it presents its result in the stdout window. To find the two strings on the same line, enter a zero for the number of lines. Zero characters means the two strings must be found right together with no characters in between. Dual Batch Find is a sort of mini-grep for dummies (like me). hAWK can perform full grep searches if you need the extra power (but in practice I've found that setting up grep searches is too error-prone for casual use). Both strings that you enter in the Dual Batch Find dialog obey the "Match Words" and "Ignore Case" options that you select in the main Find dialog. § <Tab> and <Return> A plain <Tab> will jump your cursor from one edit field to the other, and a plain <Return> is the equivalent of the “Find” button. To enter a <Tab> or <Return> in either the find or the replace text, hold down the <Command> key while typing the character. § Find again This menu command is the equivalent of the “Find” button in the Find dialog, and finds the next instance of your find string in accordance with your Find options (see above). Find Again searches the front window, or, if the Find dialog is in front, the window just behind the Find dialog. Find Again also works with the project window, allowing you to search for part of a file name in a long list of files. It searches the active pane only (the one with filled-in scroll bars). § Enter selection Enter Selection will replace your current find string with whatever text you have selected. It works with any text window including lookup windows, and also the project window (in case you wish to search for a file name). If your Find dialog is on–screen, you will see the new find string in the dialog. § Recent finds are remembered Your most–recent find strings will be stored in the popup “Find:” menu at top–left of the Find dialog. Selecting an item from the popup will copy it to your find string box. Two minor limitations apply: find strings containing <Return>s or more than 48 characters will not be remembered by the popup menu. § Replace Replace can be thought of as a Paste for short strings (up to 255 characters). The replacement text is taken from the replace string in the Find dialog. No checking is done to see if the selection that will be replaced corresponds to your find string, so the replacement string can in effect be used as a second (small) clipboard. To set up a choice between two “Paste” alternatives, enter one selection into the replacement string in the Find dialog, and then Copy the other selection. Then Paste or Replace in your document as appropriate. If the Find dialog is in front, Replace will affect the window just behind the Find dialog. Replace is undoable provided the window in which the Replace was done is in front, and provided you don’t perform some other undoable action before undoing. § Replace and Find Again This command is the exact equivalent of Replace followed by Find Again, and is undoable. § Replace All Unlike other search commands, Replace All cannot be called when the Find dialog is in front—you must specifically bring frontmost the window in which you wish to use Replace All. This small awkwardness is an attempt to remind you that Replace All is the one editing command that can make a real mess of your document. However, it is undoable—as with other undoable operations, you need only have the correct window in front before undoing. If you have selected the “Wrap Around” option in the Find dialog, Replace All will indeed replace all instances of the find string with the replace string throughout your document. If “Wrap Around” is not checked, replacement will be done only below your current position in the text. To prevent a single instance of the find pattern from being replaced, select at least the first character of the instance in your document just before Replace All (selecting all of it will do). § Multi–file searches Any file in your project can be added to a list of files to be searched. Files that are included in a multi–file search will have a bullet • just to the left of the name in the project window. “Coarse” setup of the multi–file search is done with the small buttons in the lower–right of the Find dialog. These allow you to select all files of a particular type—.c, ".h", <.h>, or plain text. The “None” button will clear the multi–file search selection, and the “All” button will add all of your project text files to the list. A counter in the Find dialog shows how many files will be searched. To “fine–tune” your list of files to be searched, hold down the <Option> key and click on or drag over the files in the project window. The cursor will change to an eye, and bullets beside the file names will appear or disappear as you drag up and down over the files. There is an illustration of this near the beginning of this chapter. Once your files are selected (and you’ve entered what you want found in the find string in the Find dialog) select Find In Next File or click the equivalent button in the Find dialog. As the search progresses, you will see the bullets beside file names in the project window disappear as each file is searched. The counter in the Find dialog will also count down the number of files remaining. If an open file is searched by Find In Next File, it will be searched from the beginning of the file. When an instance is found, Find Again will locate other instances in the same file. To continue the multi–file search with the next file, select Find In Next File again.When all files have been searched, you’ll hear a beep, the counter in the Find dialog will read zero, and all bullets will be gone from the project window. Even if you don’t find anything, it puts on a nice show. A <Command><period> will interrupt a multi–file search, and also clear the list of files to be searched. To generate a list of all instances of your search string, click the "Batch" check box before doing your Find In Next File. Results of the search will be shown to you in the "$tempStdOut" window in the format «file name» line-number line-where-found, and to view a particular instance in its original context click on the line and use "Go to...". Note that the "Find in Next File" button changes to read "Batch Find" if you click the Batch checkbox in the Find dialog, and the corresponding menu item under the Search menu changes as well. By the way, your list of bulleted files in the project window can also be used to remove those files from your project (see “Remove •'d Files” in the “Projects” chapter), and used by a hAWK program as a list of input files (see Appendix 2, and the hAWK User’s Manual on disk 2). § Skip '-' : excluding files from a search In the Find dialog, the "Skip '-'" checkbox lets you exclude project files that are marked with a dash '-' when carrying out a multi-file operation such as searching. These dashes are primarily used to exclude files from a dictionary build, and are placed by holding down the <Command> key and clicking on the file's name in the project window. But you may also wish to skip over these files when multi-file searching: if so, you should turn this checkbox on in the Find dialog before carrying out the search. Note if the "Skip '-'" option is on, then files with a '-' beside them will not be passed to hAWK in your multi-file selection, and they will not be removed from your project when you pick "Remove •'d Files", whether or not they have bullets beside them. Neither will they be selected or deselected for searching if you click on the "All" or "None" buttons in the Find dialog. If you have the "Skip '-'" checkbox turned on, then when you fine-tune your multi-file selection by <Option>clicking in the project window you will not be able to place bullets beside files that have a dash '-' beside them. But note that "Skip '-'" takes precedence, so if you put bullets beside files that have dashes and then turn on "Skip '-'", those dashed files will not be included in multi-file operations. At any time, the "Files to search:" number in the Find dialog accurately shows the total number of files that will be searched, so if "Skip '-'" is on then dashed files will not be included in the total. To run a multi-file operation (such as the hAWK program "$EchoFullPathNames", or a Batch Find) on just files that are not marked with a '-': • select "Skip '-'" • mark the files with bullets (eg by clicking the All ".c" button or by holding down the <Option> key and clicking on project file names) • run the multi-file operation. To run a multi-file operation on all EXCLUDED files, ie those that are marked with a '-': • deselect "Skip '-'" • click the "All" button in the Find dialog • select "Skip '-'" • click the "None" button in the Find dialog (this will leave bullets beside files marked with a '-') • deselect "Skip '-'" again so the bulleted files won't be ignored • run the multi-file operation. § THINK Find commands Located under the Search menu near the bottom, three commands allow you to make use of the THINK Project Manager's "Find" results from within EnterAct. To use these commands, you must use THINK C 6 or later, and set up EnterAct as the Project Manager's editor as described in Appendix 4 here. After completing a "batch" find in THINK C, you can use the THINK Find Again and THINK Find Previous commands to step through the results. These two commands work only with the results of a batch find. To start or continue a multi-file search using the THINK Project Manager's multi-file search rather than EnterAct's, use the THINK Find In Next File commands after setting up the (non-batch) search in the THINK Project Manager. Note this means you can perform and even alternate between two separate multi-file searches, THINK's and EnterAct's. Find in THINK Reference does the same thing as the command of the same name in the THINK Project Manager's editor: it passes your currently-selected text over to THINK Reference, where you'll be shown any entry it has on the name in question. Note this works only with THINK Reference version 2 or later. To use EnterAct's "Find in THINK Reference" command under any circumstances, create a folder named "Tools" or "(Tools)" next to EnterAct and drop an alias of Think Reference in it. Find in Toolbox Assistant is much the same, just drop an alias of QuickView in your Tools folder. - - - - - - - - - - - - “Go” commands - - - - - - - - - - - - Of the four “Go” commands under the Search menu, the most important is the “Go to” command. This command allows you to jump to any marked position in any project file, and since the marker position is maintained as you edit, so is your ability to jump to it. The standard suite of “go” capabilities is also available. § Go to Top/Bottom The Go to Top and Go to Bottom menu commands do the same thing as <command><up arrow> and <command><down arrow>, namely take you to the top or bottom of your text window. They also function in the project window. § Go to The “Go to” command allows you to jump to a fixed position or a marker, based on the text you have selected in your front window. The position or marker can be in any project file. For example, you can jump to a specific marker in a specific project file with “Go to”. And there is an easy way to generate the file name and marker name text (pick the marker from its popup marker menu while holding down the <Shift> key), as explained in “Going to markers” a couple of pages ahead. A typical link of this form in your code might look like ____ /* See «MyProject Log» «Conversation with J.B. re New Features» */ ____ where the project file is “MyProject Log” and the marker name is inside the second set of Euorpean quotes «». You could jump to the marker in your “MyProject Log” file by clicking anywhere on the line mentioning the file and marker and then selecting “Go to”. Selecting the entire file name and marker name including the surrounding «» quotes would also work. Since markers are maintained by most editors (EnterAct, THINK C, and MPW for example), links of this form will also be maintained as long as the marker exists and the file is in your current project. If both file name and marker name are in «» quotes, then both file and marker name can be highly abbreviated, eg ____ /* See «Log»«J.B. News» */ ____ —as with regular lookup, your spelling just needs to be “distinctively close”, in terms of runs of matching characters when comparing against file and marker names in your project. “Go to” also works with file names or marker names alone, or with line and character positions in a file, or with file name followed by line and character position. And it also accepts full path names. The following terms are used below to help summarize selection possibilities: • file_name: the name of a project file, optionally enclosed in European-style quotes, ie «». Your selection will be extended to include any trailing file extension (such as “.c” or “.NOTES”), provided your basic selection is not by itself the name of a project file. This could also be a full path name. • marker_name: the name of a marker in a project file, optionally enclosed in European style quotes «». Note the name of the marker should be specified, not the text (if any) that is selected when you jump to the mark. • text_position: line number, optionally followed by character position on the line, for example 123 6 to specify the 123rd line in a file, just before the 6th character. The first line in a file is line 1, and the insertion point before the first character on a line is character position 1. • other_text: by itself, text that is none of the above; following a file_name, text that is not a marker_name or text_position. • insertion_point: an empty selection. “Go to” acts on selections in the following ways: • file_name : open the project file, or just bring it to the front if open • marker_name : equivalent to selecting the marker from the window’s marker menu • text_position : go to the position specified • file_name marker_name : open the project file or bring it to front, and go to the marker specified • file_name text_position : open the project file or bring it to front, and go to the position specified • file_name other_text : open the project file or bring it to front, then use “Find” on the other_text in an attempt to locate it • other_text : display a dialog in which to enter a line number to jump to. • insertion_point : if the text of the link is quoted, ie file_name or marker_name if present are within «» quotes, then clicking anywhere on the line is sufficient to select the link for goto purposes. Otherwise, you will be shown the line number dialog, as with “other_text” Note if both file name and marker name are in «» quotes you can use extremely abbreviated versions of the names: the file name just has to be "distinctively close" to the name of a project file, likewise the marker name to a marker in that file. Selections intended for the “Go to” command are called “Go to” selections or “Go to” links in this manual. Here are some examples: (a file_name link: note selecting the “.h” is optional) (file_name in quotes followed by line number and character position on line—for “Go to”, any insertion point on the line will do) (instead of an insertion point, you can select all of the file_name text_position) (unquoted version of the same) (file_name marker_name: with both in quotes, your selection can be an insertion point anywhere on the line, here between the file and marker names) (without quotes, you must select the entire file_name marker_name) (a marker-name link in the document “Proj Interface.DSGN”? Probably. But it could also be a file name, or a marker in some other document. The context of your current project and front window will determine what «Modifier keys» is, and where you go to. Note for “Go to” purposes, you could also just click in the line rather than selecting. The one important restriction on “Go to” is that if you specify a file name, the file you are going to must be in your currently open project. If it isn’t, you can add it with the Add Files command. To resolve ambiguity, file names take precedence over marker names. And if you should have a marker name that looks like a text position, enclosing it in quotes«» will force treatment as a marker name. The file name can be the name of a PICT file, by the way, allowing you to use single pictures as popup illustrations. And “Go to” works with file names selected in the project window, performing the same as if you double-clicked on the file name to open the file. Spaces or tabs before, between, or after the components of a “Go to” selection will be ignored. Hence the enclosing «» quotes are required if a file name or marker name begins or ends with “white space”. Otherwise they’re optional, but quotes do help “Go to” selections to stand out quietly from the surrounding text. And if both file name and marker names are quoted, clicking anywhere on the line is equivalent to selecting both parts for “Go to” purposes, a handy shortcut. Quotes are included when you copy a marker name (and file name) from a marker menu, as explained in “Going to markers” on the next page. If you have included a file name in your “Go to” selection but are immediately shown the line number dialog instead of the desired file, this means you haven’t yet added the file to your project. If you see a message that the file couldn’t be found, this means the file has been moved, renamed, or deleted since you added it to your project, and the solution is to delete the file from your project and re-add it. If a line that you go to seems to be the wrong line, this normally just means that the file has been edited (lines added or deleted) since the line number was specified. And if going to a marker doesn’t work, this usually means that the marker has been deleted from the file (note that if you delete the actual text marked then you lose the marker, even if you immediately undo the delete). File-name line-number links are of limited use, since the line numbers can quickly become obsolete. Links of this form are however generated by EnterAct and by hAWK programs when displaying lists of positions (see the next section). File-name marker-name links are better for your own use since their locations are maintained for you, and you’ll find in the “Going to markers” section below an easy way to generate the necessary text for them. And any existing mention of a file name or marker name in any of your project documents is now a “Go to” link, as you no doubt gathered -- just add the corresponding document to your project. § Going to included files To jump to the top of an included file such as ____ #include "thisheader.h" ____ click on the line and select "Go to...". Note if you have more than one header file with the same name in your project you might not get the right one. (To toggle between a source file and its corresponding header, such as "File.cp"/"File.h", use <command><tab>.) § Going to text positions Text positions compatible with the “Go to” command are displayed by the Show Activities command, for example: ____ ¶60 Sat Jan 16, 1993 10:51:48 pm PASTE «hAWK_FilesandClip.c» 390 4 =>inserted 50 characters: «if (!dirs && !(fpb->ioFlAttrib & 16)) /* a file */» ¬ ____ To see the place where this paste took place, you would select “«hAWK_FilesandClip.c» 390 4”, or just click in the line somewhere, and then “Go to”. For details, please see the “Show Activities” chapter. For now, note that the Show Activities command can update the text positions (and even file names) for you, to keep them as current as theoretically possible, which is to say almost always useful. Many hAWK programs generate file-name line-number text that is compatible with the “Go to” command. For example, $CompareFiles shows document differences in this form, and $XRef generates file name and line number listings for C terms in your source code. Several of the Index commands under the EnterAct menu also generate line numbers. Text positions can be used to link documents together, but you’ll usually find it better to use marker names instead (see just below). The reason is that marker positions are maintained as you edit files, whereas line numbers can go out of date quickly. § Going to markers The ability to “go to” any marker in any project file means you can use a file name followed by a marker name as a true “hyperlink”, especially useful for placing references to supporting documentation in your source files or other documents. To generate the necessary text for establishing a file-name marker-name link: • open the file that contains the marker • hold down the <Shift> and <Option> keys, and click-and-drag in the window’s title bar to access the popup marker menu; select the marker you want • the link, in the form «file name» «marker name» , is now on the clipboard, ready for pasting. • (note <Shift> <Command> will also work when picking from a marker menu) EnterAct places «» quotes around both the file name and the marker name. To generate file-name marker-name link text for all markers in one or more files, use the "Index Marker Names" command under the EnterAct menu, as described in the "'Index' commands" chapter. With quotes around both the file name and marker name, you can “select” a file-name marker-name for “Go to” purposes by clicking anywhere on the line if it's the only link on the file, or between the two quoted bits of text otherwise. Your selection will be expanded to include the quoted file name and marker names when you pick “Go to”. And with both file and marker name in «» quotes you can use highly abbreviated, even slightly incorrect versions of the names, provided those names are distinctively close to the names of a file in your project and a marker in that file (in terms of case-sensitive runs of matching characters). To go to the position referenced by a file-name marker-name link, click on the line containing the link text, and then issue a “Go to” (see next illustration). On the chance that too many new things at once have pushed some old things out the bottom of your memory stack, a reminder that to jump to the definition of a term that’s in your current project dictionary just <Option> double-click on it. File-name marker-name links are mainly for jumping to places in your (unparseable) supporting documentation. Tip: if you want to be able to jump to an illustration in a text file, mark its location and then copy the marker name for pasting elsewhere. § Go Back This command takes you back to your last signficantly different position in a text file. Usually the two positions will be in the same file, and a typical use is to “toggle” back and forth within a function between the spot where you’re creating code and the top of the function where the locals and parameters are declared. Whenever you move your insertion point or make a new selection, you define a “significantly different” position to go back to if you: bring a different text window to the front, or; click more than 3/4 of a window away from your previous position. You can alter your current position without spoiling the memory of your previous position by inching along—click half a window away, scroll, click half a window away, scroll…. You can also toggle between two positions in a file with markers, or “go to” links, or by pressing <Enter> to switch between the top and bottom ends of a large selection. (Note the link text «hAWK User's Manual» «F Running hAWK programs» could have been abbreviated as say «hAWK Man»«running» —when both file and marker name are in «» quotes, the file and marker names just have to be reasonably close to the actual names.) - - - - - - - - - - - - - - Markers and the Locations menu - - - - - - - - - - - - - - § Introduction A “marker” is a marked location in your text consisting of a start point, an end point, and a name to be associated with the marked position. Typically, you’ll place markers in your C source files all at once with the Automark command, and you’ll place markers in supporting documents one-at-a-time with the Mark command. Marks can be placed in header files with Automark, but you may prefer to use Mark. To bring up a popup menu of a window’s markers, hold down the <Option> or <Command> key and click in the window’s title bar. EnterAct's default behavior is to automatically generate markers for all functions in source files and all struct/class definitions in header files as you open or save the files, and to not save those markers with the document. If you manually insert markers in a document that goes in your project's rightmost (documentation) pane, these markers will be saved with your document when you save the file (this manual is an example). You can force EnterAct to save source and header file markers with your files by enabling the the “Save source/headers marks” option, but the only use for this at present is to allow the “Index Marker Names…” command to index marks in your source files. At present EnterAct does not support #pragmas for inserting special markers in source files. Markers do stay attached to the proper position as you edit the file around them, but any editing that’s done inside the marked range will correspondingly expand or shrink the range associated with the marker. If you remove all of the text that is within the marked range, you will also remove the marker, and this is not undoable. Markers do not survive cutting or pasting—they stay attached to the text only as long as the text remains in the document. The Automark command is mainly useful to mark all of the function definitions in a source file, though it has other options, and can be used to mark a variety of C constructs, with the option of marking just the first in a group. There is little need for this command, since EnterAct's default behaviour is to mark source files for you without your intervention. Marker names can be used as links within or between files, in conjunction with the “Go to” command. Called “Go to” links, these take the form ____ «file name» «marker name» ____ where the enclosing «» quotes are usually optional. Where a link is present in your text, you can go to it by selecting the file name and marker name (including «» quotes if present), or by clicking anywhere on the line, and issuing the “Go to” command. For an easy way to generate the text for these links, see “Copying marker names” below. You’ll find details on using “Go to” links in the “‘Go’ commands” chapter. Please note your markers will be maintained properly only by editors that implement MPW–compatible marks. This includes just about all editors. § Mark To place a single marker, select either an insertion point or the range of text that you want remembered, and then select the Mark command. You will be asked to supply or modify a name for the marker: click Add, and then forever after you will be able to jump to that marker whenever you want (marks are saved to disk and properly maintained). § Marker menus Every document containing marks has a popup marker menu associated with its window. To jump to a marker, hold down either the <Option> or <Command> key or both and click-and-hold in the title bar of your window. You’ll see a popup menu listing all of the markers attached to your file. Pick one, and you go there. The markers are in alphabetical order. If the name of a marker is present in your text, you can also go to it by selecting the name and using the Go to command, as explained in the “‘Go’ commands” chapter. § Unmark To remove one or more markers, select Unmark. You will be presented with a list of markers to select for deletion. This list follows the standard Macintosh rules for list selection: click with no keys held down to select a single marker (this deselects any other selected markers); click with the <Shift> key down to select a contiguous range of markers while dragging the mouse; and click with the <Command> key held down to select a marker that is away from other selected markers (the markers in between are left unselected). To quickly remove all markers from a document, use the Automark command with only the “Clear all present markers first” option checked. § Automark This command is largely obsolete, and not recommended for any purpose except removing all marks from a file that lives in the documentation pane of a project. EnterAct's default behaviour is to mark all source and header files for you automatically, and this should be all you need. This command works with any first-draft or compilable C file, whether or not it has been added to your project. The Automark command can be used to remove all marks from any file (source or not), by checking just the “Clear all present markers first” option. If you wish to keep special markers that you have manually added, leave “Clear all present markers first” without a check mark. When a duplicate name or position is found while adding markers, the new entry will replace the old one. The “first of group only” checks have slightly different interpretations: for #defines, it means mark only the first of a group of consecutive #defines; for enum constants, it means mark only the first within an enum {} statement; and for variables it means mark the first of a group of consecutive variables, whether they occur in the same statement or in separate statements. If you leave some types unselected then EnterAct’s automarker won’t count them as separating, say, two groups of variables or #define’s. To keep things sane, there is a limit of 499 marks to a file. This is a 9 foot popup menu, a bit tedious to scroll through even with a 68070. Marker names are limited to 63 characters, but the range of text you mark with the name can be as long as you want. § Copying marker names To put text of the form «file name» «marker name» on the clipboard for a particular marker, hold down the<Shift> key and either the <Option> of <Command> key while clicking in the title bar of the marker’s window to access the marker popup menu; selecting the marker from the popup will put the text on your clipboard. This is the same as going to the mark by selecting it from the popup marker menu, except that in addition you hold down the <Shift> key. Text of the form «file name» «marker name» can be used with the Go to command to jump to any marker in any project file, and variations on this theme are available as detailed in the “‘Go’ commands” chapter. § The Locations menu This menu allows you to mark and jump to up to 10 different locations. You can mark positions in any text file, and they stay recorded in the Locations menu until you delete them, independent of whatever project you might have open. This is a generalization of the "Go Back" command, allowing you to go back to any specific location. If you edit files with some other editor, your remembered locations may be thrown off, in which case you could delete and re-add them. (Function and struct markers that are created automatically by EnterAct are not thrown off if you edit files with some other editor.) To add a position to the Locations menu: • select the position you want, and optionally some text there • pick Add Current Location from the Locations menu • a dialog will appear which allows you to set the position's name as it will appear under the Locations menu: if you selected some text at the position to be marked, that text will appear in the dialog. You can edit the name, put in an arbitrary name, or have no name at all--in this case, EnterAct will concoct a name for you, made up of the file name, line position, any enclosing function name and maybe other stuff. To jump to a position you've added to the Locations menu: • pick it from the Locations menu. To delete a position from the Locations menu: • go to the position (pick it from the Locations menu for example) • select Delete Current Location from the Locations menu • if the location can't be found, you will be asked if you want to delete the location from the menu. When you hit the limit of 10 marked locations, you won't be able to add any more until you delete one of the remembered locations. - - - - - - - - - - - - Options, under the Edit menu - - - - - - - - - - - - § Introduction You can change any of the options at any time. Defaults for the options have been selected to give best performance under average conditions. Options are saved with EnterAct itself rather than a project. Some of them you’ll set once and forget, but the number of lookup windows and the number of entries per lookup determine how cluttered your screen can get, and how many alternate entries a lookup window will hold, so you’ll vary these two numbers to suit particular circumstances. For a discussion of “Safe switching under MultiFinder” see the next chapter, “Switching to other applications”. For a discussion of “Save activities to disk” see “Show Activities” near the end, in the section “Turning activity recording on and off”. § Number of lookup windows This box allows you to set the maximum number of lookup windows that can appear on–screen at one time. For complicated situations you may want more than 4, whereas on a small screen you may prefer fewer than 4 to avoid clutter. § Number of entries per lookup window The number in this box determines how may dictionary entries will be retrieved in a lookup window, if your spelling does not match any term in the dictionary exactly. If your spelling does match a term exactly, all exact matches will be retrieved, up to a maximum of 60. You may wish to temporarily increase the number in this box if your recollection of the spelling of a term is shaky. On a regular basis, you may prefer 3 or 5 entries rather than 4—a bit of experience will tell. § Remembering window locations By default, EnterAct will remember the window locations of all your documents (saved in a small resource with the document). Also, you will not be asked if you want to save changes to a document when you close it if the only change is a change in window location (the “don’t pester” option). You can take advantage of the remembered window locations to work with groups of documents; arrange each group nicely on the screen, and then if you later reopen the documents in that group they will be arranged on–screen where you left them. § Long or short windows If there is no remembered location for a document, or if you have switched off the “Save document window locations” option, then a newly–opened window will come up near the top of your screen, with a relatively short or long length according to what you select in the option “Windows open short/long by default”. You may not notice much of a distinction if you have a small screen. This short/long option always governs the appearance of new text windows, and of text files created by other applications that have never been saved while using EnterAct. § Reformat Selection options Reformat Selection will rebreak the lines in a selection of text to improve the appearance of the right margin. Aside from selecting a “ragged right” or “full justification” look, you can also set the maximum number of characters per line in the “Reformat line width” box. The default of 74 gives a reasonable and printable line in Monaco 9. § Detect nested comment starts This option is on by default, meaning that EnterAct will accurately trap any single failure to properly start or end a comment, both while building your dictionary and while balancing. If you are in the habit of doubling up on comment starts, as in ____ /*#define Flag37 /* if defined, use SlowDraw */ ____ and if you are not willing to mend your ways, uncheck this option: comment starts within a comment will then be ignored for dictionary and balance purposes. Just make sure you type carefully! § Ignore 'ckid's A 'ckid' is a resource that SourceServer uses to keep track of whether a file is modifiable or read-only, and also if the file's status has been changed from read-only to modifiable by an editor while the file was checked out. EnterAct obeys these resources (a "no pencil" icon appears in the window's display box for read-only), and allows you to make changes to a read-only file after you select the "Modify Read Only" command. Selecting "Ignore 'ckid's" in the Options dialog will force EnterAct to completely ignore these resources. You’ll be able to edit a file that was checked out as read-only, and the SourceServer will never know. This can really screw things up. Don’t do it. There, you’ve been warned. § Relocate files automatically When this box is unchecked (the default), EnterAct will present a dialog asking you to relocate a file whenever it loses track of where a file is. This typically happens when you trash a whole folder and replace it with a newer version. If you check this box, then if EnterAct loses track of a file it will attempt to relocate it without your help, by searching down from the top level of the disk where it was last seen. If this doesn't work, you'll still be asked to help. Check the "Relocate files automatically" box only if you're sure that each of your source files is uniquely named on the disk where you've stored it. If you can't guarantee that, then please leave the box unchecked, and put up with the occasional request to relocate a file -- it's no more painful than resetting file paths with Code Warrior. Note that if you just move a folder around on the same disk, or rename a folder, EnterAct will still keep track of where the contained files are. To make EnterAct lose track of a file, you have to move it to a different folder, including the case of trashing a folder and replacing it with one that has the same name. (What about renaming the file? From EnterAct's point of view, if you rename a file then it's a different file, and you'll have to add it separately to your project.) § Automark source files The "AutoMark source..." check box will create marks for all functions in a source file when you open it, and marks for struct and class definitions in headers. The marks are redone (to pick up new functions etc) whenever you access the popup marker menu for a file after editing it, or when you Save a file. “Automark source/headers...” is ON by default. § Save source/headers marks You can force EnterAct to save source and header file markers with your files by enabling the the “Save source/headers marks” option, but the only use for this at present is to allow the “Index Marker Names…” command to index marks in your source files. “Save source/headers marks” is OFF by default. § Append arguments for automarked functions This checkbox (see illustration above) controls whether summaries of arguments to functions and methods are appended in the popup marker menu for source and header files. This is ON by default. It's handy for distinguishing between functions with the same name that take different arguments, and for a quick reminder of what arguments a function takes. Addin the argument summaries takes a while, so if you have a slow machine you might prefer to turn this option off. It's OK on a 68040 running at 25Mhz. § Record Find, Find Again, Find Definition If you do a lot of Find's and jumping to definitions, these activities can clutter up your activity log. Turn this option off if you'd rather have your activity log hold just the more interesting activities, and don't mind losing some information about where you went. This option is ON by default. - - - - - - - - - - - - Switching to other applications - - - - - - - - - - - - § Under the Finder (System 6) There are some nifty INIT’s that will let you switch between applications under the Finder almost as quickly and easily as if you were using MultiFinder—On Cue and Master Juggler come to mind. (OK, you got me - this manual was started in 1990, and there are a few "fossils" here and there....) Whatever means you employ to switch to another application from EnterAct while under the Finder, you will be asked if you wish to save any documents that need saving, and they will all be closed. The situation with MultiFinder (or System 7) is different , since documents can be left open when switching to another application. § Under MultiFinder (or System 7 or later) If you switch from EnterAct to some other application while under MultiFinder or System 7, you will not be required to close your documents. This means that while using the other application you could attempt to access documents that you have left open in EnterAct. If this potential conflict weren’t handled, you could end up working with two different versions of the same document, and inevitably you would lose one version. One solution to this problem would be to prevent you from opening that document with any other application if it is left open in EnterAct. This restrictive “my file and you can’t have it” attitude is appropriate if an application is meant for use on a network, where several people could want access to the same file at once. However, EnterAct is not meant to provide source code management with multiple users (many packages such as Projector, VOODOO, MW CodeManager etc can be used in addition to EnterAct to provide full source code management), so it does not take this approach. Instead, when you switch, all open documents are quietly saved if they need saving and have ever been saved before (“untitled” documents present no problem—you can’t get at them with another application). In addition, when you return to EnterAct, EnterAct will check your disk to see if you have altered any of the open documents while you were away—if so, they will be quietly reloaded. EnterAct, if effect, opts for the “low man on the totem pole” position when it comes to having control over file access, and does the necessary behind–the –scenes work to allow you to leave files open and still be able to open and change them with other applications. To make this bulletproof, it will be safest if you close all text documents when leaving the other application, since that other application will typically not be able to compensate for files being changed “behind its back” in EnterAct. You can, if you wish, defeat this protection by unchecking the “Safe switching under MultiFinder” option in the Options dialog. However, EnterAct will not restrict access to open files when you switch, so you will be entirely responsible for ensuring that you don’t end up with two versions of the same file floating around. Closing all open text documents before switching would be sufficient. Safe switching protection can also be defeated on a per–switch basis, by holding down any of the <Shift>, <Option>, or <Command> modifier keys while you switch. Holding down a modifier key while you switch out from EnterAct means that unsaved changes to files will be left unsaved, and when you return to EnterAct any files open in EnterAct that were changed elsewhere will not be updated for you on–screen. Holding down a modifier key while returning to EnterAct will prevent just the updating on–screen of any files that were changed elsewhere. This is, on rare occasions, handy if you change a file with some other application, realise you’ve made a mistake but can’t revert, and wish to recover the version of your file that’s still open in EnterAct. If you wish to have several people working on the same source files at the same time with EnterAct, your best approach is to use SourceServer or some other version of source control that uses 'ckid's to mark files as modifiable or read-only. § Check the disk for changes When you edit source (.c or .h) files that are in an EnterAct project with some other application, select Update Dictionary when you reopen the project to ensure that your dictionary is brought up to date, unless you clearly recollect that you didn’t change anything outside of a function body. This update typically takes only a few seconds. Only the project you have open will track which files are changed, so if you switch to a different project you will also need to select Update Dictionary to rebuild the dictionary if any .c or .h files in the project were changed while the project was not open, whether or not the files were changed with EnterAct. Experience suggests that it's more efficient to update your EnterAct dictionary when you notice that it's producing lookup that's out of date (unless more than one person is involved, in which case you may be better off doing the Update routinely). § Working with THINK C This section describes working with THINK C as a separate application: to use EnterAct as a replacement for THINK’s own editor (the “use external editor” Edit option in THINK C version 6 or later) please see Appendix 4. If you adopt EnterAct as your C editor of choice, you’ll often change several files with EnterAct over an extended period, and then switch to THINK C to bring your application up to date. Fortunately, there is no need to keep exact track of which files you change, since THINK C’s Make command can do this for you. Call up the Make dialog, click the “Use Disk” button, and, after the brief wait while THINK C checks the modification dates of your project files, click the “Make” button to bring your THINK C project fully up to date. If you remember exactly which files were changed, you can instead select them one by one in the project window and use the “Compile” command to update your THINK C project. Conversely, if you use THINK C to make some changes to your source files, you can bring your EnterAct project fully up to date by selecting the Update Dictionary command from the EnterAct menu, as mentioned above. Note this step is not necessary if your changes while in THINK C were restricted to function bodies, which should often be the case. This is because EnterAct does nothing with function bodies except check them for balance in a few key delimiters. Editing files with THINK C, or any other editor besides EnterAct, will compromise your ability to revert files to earlier versions with EnterAct (see the “Show Activities” chapter). That’s worth remembering, but in practice the need to revert a file is so rare that you shouldn’t let it influence your editing. If you do need to revert files regularly, you're better off using some sort of version control software. - - - - - - - - - - - - Show activities - - - - - - - - - - - - § Introduction EnterAct will, at your option, keep track of your recent activities in full detail. The Show Activities command under the Edit menu generates a window holding descriptions of those activities, with details in plain English of what, when, and where. Here are three typical entries from the “••Recent Activities••” window generated by Show Activities: ____ ¶148 Tue Jan 12, 1993 8:22:23 pm OPEN «PICT saving» ¬ ¶149 Tue Jan 12, 1993 8:23:17 pm CUT «PICT saving» 45 1 (temp) <=deleted 289 characters: «/* save pict "dataH" under the full path name "fileName", on the volume "volumeName" */ /* open the file, which should already exist */ pb.ioCompletion = 0L; pb.ioNamePtr = (StringPtr)fileName; pb.ioVRefNum = 0; pb.ioVersNum = 0; pb.ioPermssn = 3; /* = fsRdWrPerm */ pb.ioMisc = 0L;» ¬ ¶150 Tue Jan 12, 1993 8:23:21 pm CLOSE «PICT saving» ¬ ____ —where, for example, “CUT «PICT saving» 45 1 (temp)” means characters were cut from the document “PICT savings” starting at line 45 position 1, and the cut was temporary, ie not saved to disk—if it had been, there would have been a SAVE before the CLOSE. Both file names and data are enclosed in European-style quotes «». Activity records are kept on disk in the log file “EnterAct Recent Activities”. This file is created and managed for you, and is preserved between sessions. Your most-recent 10,240 activities will be recorded in full detail, up to the limits of 65,535 characters per insert or delete, and a total of 1,310,720 characters of inserts and deletes for the 10,240 activities (typically only 1/4 or less of that is needed). Everything of interest, including all edits, searches, open/close/save/save as, switching in and out, etc will be recorded. Armed with a display of your recent activities, you will typically be able to: • remind yourself of what you did recently (another form of “context restoration”) • selectively undo or recover the contents of any recent insert or delete • generate a reverted version of a file, back to a particular activity (multiple files can be done one file at a time, back to different activities) To turn the recording of activities off temporarily, select the menu item named Recording activities under the Edit menu: it will change to read Not recording activities. This is a toggle, and selecting it again will turn recording back on. Your recording status is remembered between sessions. If you’re just interested in a quick first look, skim through the “What’s shown” and “Reviewing activities” sections later in this chapter. To revert one or more files, you’ll need to follow the checklist in the “Reverting a file” section, since the procedure is relatively lengthy. For other uses of the “••Recent Activities••” window, an understanding of the format of a displayed activity is all you really need. Many obvious points are explained at length below, both to scrub away the fuzziness from some intuitive notions and to introduce you gently to what is, at heart, a simple way of keeping track of what you’ve done recently. § What’s recorded Full details on the following activities are recorded in the log file “EnterAct Recent Activities”: • all edits which affect your text, including typing, Cut, Paste, Paste Selection Behind, Undo, and replacements done with any of the replacement commands under the Search menu. The only notable edit exception is Copy • all search results, in one or multiple files • session start and end, switching in and out, running a Drag_on Modul • Open, Close, Save, Save As, Revert, for text, lookup, PICT, and project windows (when applicable) • Go to, Go Back, Go to Top, Go to Bottom, and jumping to a definition After starting EnterAct at least once, you’ll find your log file in the same folder as EnterAct itself, and you’ll probably be able to identify it as a “log” file just by its icon. Note that it is not a text file, at least not entirely, and its contents can be shown only with EnterAct’s Show Activities command. For each activity, the following information will be recorded, if appropriate: • the name of the activity (eg TYPING, SAVE, RUN DRAG_ON MODULE) • the time at which it occurred • the name of the file in which it occurred • the position in the file at which it occurred, specifically the starting position if it was an insert, delete, or Find of some sort • for inserts and deletes, the full contents, and the size of the edi • for search and replace, the found text and the replacement text • for Save As only, the previous name of the window. Inserts and deletes are recorded as separate activities, even if they result from a single command. For example, pasting over a selection will be recorded as a delete followed by an insert: ____ ¶7 Wed Jan 13, 1993 9:27:52 pm PASTE «Untitled-1» 1 1 <=deleted 35 characters: «This text was deleted when pasting.» ¬ ¶8 Wed Jan 13, 1993 9:27:52 pm PASTE «Untitled-1» 1 1 =>inserted 38 characters: «This text was pasted over a selection.» ¬ ____ The recorded file position of an edit is of course the position as calculated at the time the activity occurred. Thus, for example, if you inserted some text at line 100, character position 3 in a file, the recorded position will be line 100, position 3. However, a subsequent edit before the position of that insert, for example a delete of lines 20 through 29 in the same file, will alter the position you would want to examine if you now went looking for that insert, assuming you saved your file. Instead of finding the inserted text at line 100, you would find it at line 90. This is called the “updated” position of the activity. As you’ll see in “What’s shown” below, you have the choice of showing either original or updated positions. § Recording limitations EnterAct does not record activities carried out in other applications, in particular changes to text files. Editing files with some other editor (such as THINK C) will compromise your ability to recover reverted versions of files using EnterAct’s multiple undo capability, in the following ways: • if the edits elsewhere involved adding or removing lines, you will probably not be able to usefully revert the file with EnterAct • if the edits elsewhere were fairly small, and did not involve adding or removing lines, then you will probably be able to recover a useful reverted version with EnterAct, but the small changes you made elsewhere will not be reflected in the reverted version. Only your most-recent 10,240 activities will be recorded in the “EnterAct Recent Activities” log file. The contents of your inserts and deletes will be recorded up to a limit of 1,310,720 characters total for all activities. In addition, inserts and deletes will be fully recorded only if they do not exceed 65,535 characters. For edits exceeding this limit, only the first 1,024 characters will be recorded for reference. Typically: • 10,240 activities represents several days of work. If you want to estimate how far back your activity log goes, bear in mind that inserts and deletes are recorded as separate activities, a run of characters typed without changing the insertion point counts as a single insert, and usually for every insert or delete there is one activity of some other kind such as a save or search. For example, at 4 activities per minute on average, you'll be logging your last 40 hours. • large edits are rare enough that you won’t run into the recording limits. Your average number of characters per activity will probably be under 50, and, if you’re slightly paranoid like the rest of us, you will probably deal will very large edits by using Save As rather than Cut and Paste. Minor activities, such as scrolling or changing windows, are not recorded. To avoid cluttering your activity log, a Replace All that is just used for counting purposes is not recorded in detail. Based on personal experience, the limitation that most affects the quality of recorded activities is of the “is it plugged in?” variety. If you turn recording off temporarily, remember to turn it back on again later! § Showing your recent activities Selecting Show Activities from the Edit menu produces the following dialog: Select the “updated current positions” button to have activity positions updated as much as possible. Select the “originally recorded positions” button to leave line numbers and character positions unchanged from their originally recorded values. For review or single undo, you’ll want updated positions, but in order to perform a multiple undo the original positions are required. You may show up to 10,240 of your recent activities, and as you alter the number of activities to show the “Memory needed” display at bottom of the dialog will update. Showing a few activities will take 700K or so of memory, and showing all 10,240 may require a couple of meg or more. If you will need more memory than is available, try closing all windows including your current project. When you click the OK button, a plain-English description of your activities will be generated, and shown to you in a window titled either “••Recent Activities••” if you selected original positions, or “••Recent Activities (updated)••” if you selected updated positions. If you’re only interested in your last few activities, adjusting the number of activities to show to a small number will reduce the time it takes to generate this description. "Show full path names for files" is useful if you have more that one file with the same name. This will require slightly more memory for all that extra text. § What’s shown Here’s are some typical entries selected from a “••Recent Activities••” display: ____ ¶60 Sat Jan 16, 1993 10:51:48 pm PASTE «hAWK_FilesandClip.c» 390 4 =>inserted 50 characters: «if (!dirs && !(fpb->ioFlAttrib & 16)) /* a file */» ¬ ¶359 Sun Jan 17, 1993 5:53:14 pm SAVE AS «HuffCode.c» Previous name was: «Untitled-1» ¬ ¶858 Sun Jan 17, 1993 11:47:09 pm GO TO «EnterAct log» 1417 1 ¬ ¶868 Sun Jan 17, 1993 11:50:28 pm OPEN «CEDAR_Files.c» ¬ ¶869 Sun Jan 17, 1993 11:50:28 pm FIND DEFINITION «CEDAR_Files.c» 3035 1 «GetSwitchOutTime» ¬ ¶870 Sun Jan 17, 1993 11:50:43 pm FIND «CEDAR_Files.c» 43 23 «SwitchOutTime» ¬ ¶926 Mon Jan 18, 1993 12:02:54 am SWITCH OUT ¬ ¶927 Mon Jan 18, 1993 12:07:31 am SWITCH IN ¬ ¶1001 Tue Jan 19, 1993 11:09:56 pm END OF SESSION ¬ ¶1002 Wed Jan 20, 1993 8:00:49 pm START OF SESSION ¬ ____ The first line of the activity record begins with “¶”, and is followed by the activity number. The oldest activity shown is number 1, followed by later (younger) activities up to the last thing you did, and its number may be as high as 10,240. The second line of the activity record shows the date and time, followed by the name of the activity. These are present for all activities, and for some activities (such as SWITCH OUT ) that may be all there is before the ending “¬”. If the activity involves a file or window, its name will be shown next inside European style «» quotes. And if the activity relates to a specific position in the file, this will be shown after the file name. The position is for the start of the activity, and consists of the starting line number followed by the character position at which the activity started on that line. The first line in the file is line 1, and the position before the first character on a line is position 1. The third and following lines hold the data, if any, associated with the activity. For inserts and deletes, the data will be preceded by either “<=deleted xx characters” or “=>inserted xx characters” where xx is the number of characters. In rare cases where the entire edit could not be recorded, this will be followed by a number telling how many characters of the edit have been retained, for example =>inserted 98765 characters (1024 shown) The contents of an insert or delete will be trimmed if: • the edit exceeds 65,535 characters; in this case, only the first 1,024 characters will be recorded • total recorded data would exceed 1.3Meg; in this case the data recorded for the oldest edits will be progressively trimmed until enough room is freed up to record the newest edit. The governing assumption is that the older an edit is, the less important it is, regardless of size. This approach has been chosen so that you will retain multiple-undo capabilities as far back as possible. The data associated with the activity is enclosed in European-style quotes «», and no characters are appended or altered inside the quotes, though as described above characters may on rare occasions be trimmed from the end. Each activity finishes up with a “¬”, on a line by itself. The SAVE AS activity has a special format, with the second line containing SAVE AS followed by the new file name, and the third line giving the previous name of the window, with accompanying text that makes this clear. The number of activities shown will often fall a few short of the number you requested (typically by 1 or 2 per 100). These “missing activities” were originally records of your typing. A sequence of characters typed without moving the insertion point other than by typing counts as, and is recorded as, a single activity. However, there is no such Macintosh event as “end of typing”, and EnterAct is slightly conservative in its estimate of when you have finished typing in a particular spot. Basically, any recordable activity is treated as an “end of typing” event if typing was going on. For example, a Save while typing would trigger a recording of your typing up to that point. If you then continue typing in the same place, that typing record will later be deleted, and a complete record of all your typing in the same place will eventually be made. Normally this is of no consequence, and now that you know what’s happening you shouldn’t let it affect you in the slightest. § Temporary, obsolete, and undone activities Though not recorded, the “current relevance” of any activity which refers to a specific place in a file is inferred when you Show Activities. As a result of later activities up to the time at which you show them, an earlier activity may end up being currently classed as: • permanent; the document in which it occurred was saved to disk after the activity in question (ie not closed without saving, or unsaveable such as a lookup window). More accurately, an activity is permanent unless it falls into one of the following categories. “Permanent” is the default category, and permanent activities are not indicated in any special way in activity records. • temporary; the window in which the activity occurred was subsequently closed without saving, but some version of the document currently exists on disk, so that in principle at least the activity still has a recoverable context. • obsolete; not only was the window closed after the activity, but no reasonable version of the document now exists on disk. This can happen if you insert text into a new window and then close it without saving, or if you edit an unsaveable window (such as a lookup window). This can also happen when you use Save As to replace an existing file “OldFile” with a new version; at that point, all previous activities relating to “OldFile”, especially inserts and deletes, become obsolete since they were later overwritten by a new version and hence no longer have a recoverable context in any meaningful sense. • undone; a permanent activity that was subsequently reversed with the Undo command. All temporary and obsolete edits have already been “undone”, in the sense that from the point of view of your disk files they never happened. If a file is open when you select Show Activities, all edits from the last save or open of that file up to the present will be classed as permanent. However, if you subsequently close the file without saving it and then reselect Show Activities, you will find that those edits have been reclassified as temporary. And if you later save over the file by using Save As, effectively replacing its contents with the contents of some other file, then the activities will be reclassified as obsolete. If an activity is classed as temporary, obsolete, or undone, you’ll see “(temp)", “(obs)", or “(undone)" respectively in the activity record, following the file name and position numbers. Here are some examples to help bring this into focus, each followed by a brief explanation: ____ ¶25 Wed Jan 20, 1993 9:55:07 pm OPEN «HuffCode.c» ¬ ¶26 Wed Jan 20, 1993 9:55:37 pm TYPING «HuffCode.c» 4 1 (temp) =>inserted 69 characters: «This text was typed into "HuffCode.c",and then the typing was undone.» ¬ ¶27 Wed Jan 20, 1993 9:55:37 pm UNDO «HuffCode.c» (temp) ¬ ¶28 Wed Jan 20, 1993 9:55:46 pm CLOSE «HuffCode.c» ¬ ____ (Note that the document “HuffCode.c” was closed without saving. The typing is classed as temporary, which takes precedence over the undoing of the typing. The same would be true of an obsolete edit that was undone—it would be classed as obsolete.) ____ ¶31 Wed Jan 20, 1993 9:58:16 pm OPEN «Untitled-2» ¬ ¶32 Wed Jan 20, 1993 9:58:46 pm TYPING «Untitled-2» 1 1 (obs) =>inserted 87 characters: «This text was typed into the window "Untitled-2", which was then closed without saving.» ¬ ¶33 Wed Jan 20, 1993 9:58:48 pm CLOSE «Untitled-2» ¬ ____ (Text was entered in a window that had never been saved to disk, and then the window was closed without saving. The context of this activity has been lost for good.) ____ ¶34 Wed Jan 20, 1993 9:59:51 pm OPEN «RenameTesttemp» ¬ ¶35 Wed Jan 20, 1993 10:00:58 pm TYPING «RenameTesttemp» 1 37 (undone) =>inserted 94 characters: « This text was typed into "Renametesttemp" and then undone. The file was saved before closing.» ¬ ¶36 Wed Jan 20, 1993 10:00:58 pm UNDO «RenameTesttemp» ¬ ¶37 Wed Jan 20, 1993 10:01:01 pm SAVE «RenameTesttemp» ¬ ¶38 Wed Jan 20, 1993 10:01:02 pm CLOSE «RenameTesttemp» ¬ ____ (Here, the undone typing in “RenameTesttemp” was turned into a permanent activity by the following save. Only permanent undone activities are shown as “(undone)”. ____ ¶47 Wed Jan 20, 1993 10:05:22 pm OPEN «Act1» ¬ ¶48 Wed Jan 20, 1993 10:06:13 pm TYPING «Act1» 1 1 =>inserted 70 characters: «This text was typed into "Act1", made permanent by the following save.» ¬ ¶49 Wed Jan 20, 1993 10:06:14 pm SAVE «Act1» ¬ ¶50 Wed Jan 20, 1993 10:06:17 pm CLOSE «Act1» ¬ ____ (The typical case, activities that are made permanent by saving to disk. There is no special indication for permanent activities, this being the default class). A permanent activity is there right now in your disk file or on-screen, and you could, with a bit of work, undo it using the information in the “••Recent Activities••” window—provided you can untangle it from the effects of other permanent activities that followed it. An undone activity was explicitly undone and the result saved, but you could redo it in the same way you would undo a permanent activity. A temporary activity wasn’t saved, but you could, with a bit of work, redo it using the information in the “••Recent Activities••” window—provided you can untangle it from the effects of other temporary activities that preceded it. An obsolete activity no longer has a meaningful context: the window or file in which it occurred no longer exists on screen or disk, though if it was in a file you might have a backup version somewhere. § Updated file names When you edit a file and then use Save As to save it under a different name, those preceding edits really apply to the file with the new name rather than to the old name. As a typical example, when you open a new window “Untitled-3”, type in it a bit, and then save it as “FileCommands.c”, you will later remember the typing as being associated with the name “FileCommands.c” rather than “Untitled-3”. In the “••Recent Activities••” window, the file name for the typing would be shown as “FileCommands.c”. When you use Save As on a file, or Save a window for the first time, the file name for preceding activities associated with the old name will be updated to the new name. This updating is applied backwards to the point where you opened or saved the affected document (or all the way back if those activities are too old to be still recorded). § Reviewing activities If you anticipate wanting to jump to a file that contains a particular edit, in order to view it in context, click the “updated current positions” while viewing the Show Activities dialog, so that the line and characters positions shown will correspond to current actual positions in your files (to the extent that this is possible). If you just intend to skim through the activities without jumping to any files, selecting the “originally recorded positions” button will speed up the process of showing you your activities, at the expense of showing you file positions that are uncorrected for other activities. With the “••Recent Activities••” window in front, you can use Find to search for activities in the usual way. Here are some (rather obvious) things you can search for: • activity number, such as “¶314” (¶ is <Option><seven>) • date, such as “Jan 13” • time, such as “ 10:51” (put a space before the hour:minute to disambiguate it from minute:second) • activity name, such as “START OF SESSION” • file name (note including the European quotes «» sometimes helps) • contents of an insert or delete For activities with file positions, such as inserts and deletes and search results, you can jump to the file and line by clicking on the line with the file-line reference, and then picking “Go to”. For example, given ____ ¶60 Sat Jan 16, 1993 10:51:48 pm PASTE «hAWK_FilesandClip.c» 390 4 ...etc ____ to open a window for hAWK_FilesandClip.c and jump to line 390, position 4 on the line, click somewhere on the line (for example, after the ‘»’…) …and then pick “Go to”. For more details, see the “‘Go’ commands” chapter With this use or any use of “Go to”, the file must be listed in one of your project panes. If you have selected the “updated current positions” version of your activities, the “Go to” command will work reasonably well—in fact, it will work as well as it possibly can. For example, if you paste some text at line 100, and then paste in 10 lines at line 50, then the position of the first paste will be updated from line 100 to line 110, because that’s where you would find it if you went looking for it now—provided it was a permanent activity. If you didn’t save the file, thus rendering the activities temporary, then the updated position of the first paste would still be line 100, because the influence of the second paste was removed by virtue of not saving it. In other words, to redo that first temporary paste, you would still go to line 100. The limit to which edit positions can be meaningfully updated shows up for example when you delete a large chunk of text, and that deleted chunk contained earlier inserts or deletes. If you paste some text at line 100, and then delete lines 50 through 200, what should be the updated position of the paste? EnterAct will show the updated position as line 50, which, if you think about it, is the best that can be done.The positions of obsolete activities are not updated, there being no file or window to which the activity can be currently related. § Selective single undo By selecting “updated current positions” when showing your activities, you stand a very good chance of being able to identify the exact current position of any previous insert or delete. However, the updated position will not be terribly meaningful if the insert or delete was later “engulfed” by a delete (for example a paste on line 100 followed by deleting lines 50 through 200). And if the activity was an insert that was later “nibbled at” by small inserts and deletes within the original insert, you may find that you have to undo several activities instead of one, or at least mentally compensate for them. Once you have found the activity in the recent activities window, use “Go to” to jump to the current position for the activity, as described in the section above. If it still seems appropriate for undoing after viewing it in context, the procedure for actually undoing it is, alas, devoid of novelty: • to undo an insert, identify the range of the insert in your document by comparing your document with the text of the insert as shown in your activity record; then select it and clear it out • to undo a delete, copy the deleted text from your activity record and then paste it into your document at the current position for the activity. If you have edited the document in question with some editor besides EnterAct, the contents and positions of recorded activities may not be entirely accurate. But if the edits elsewhere were small, you should be able to compensate for them and still achieve the undo you want. The recent activities window does not update as you make changes. To force an update of positions and activities, close the window and reopen it. § Reverting a file > Introduction The procedure for reverting a file to an earlier form based on your recorded activities is a bit lengthy, so step-by-step instructions are given below. In order to revert a file you need to specify the file, and how far back you want to go when reverting the file. The “how far back” part is specified by an activity number from your “••Recent Activities••” window, so you’ll need to Show Activities (with original positions) to identify the right activity number. The actual revert is done with the supplied hAWK program “$Multi_Undo”, and to provide the needed input for this program you’ll save your “••Recent Activities••” window to disk, then add it to an EnterAct project. The file you wish reverted must also be added to the same project. The reverted file will be presented to you in the “$tempStdOut” window when $Multi_Undo is finished, to do with as you wish. EnterAct doesn't do version control, and this reversion process, in its present inelegant form, should be used in emergencies only. It works, but that's all you can say for it. > Limitations In order to revert a file (called file A below), several conditions must be met: • file A has been saved since its contents were last changed • All changes to file A, from to the undo point up to the present, have been made with EnterAct • From the undo point up to the present, no other file named "A" has been edited with EnterAct (ie a different disk or folder, but the same basic file name A) • The activity corresponding to the undo point is present in EnterAct's "••Recent Activities••" window (it goes back up to 10,240 activities). • The entire text of each edit on file A is present in "••Recent Activities••": you normally won't want to check for this yourself, and the hAWK program “$Multi_Undo”, which you’ll be using anyway, will do it thoroughly for you. In general, only inserts or deletes below 64K characters are fully recorded, and older large edits near the beginning of "••Recent Activities••" may not be fully recorded if it was necessary to make room for newer large edits, due to the total data limit of 1.3Meg characters. Rule of thumb: barring a sequence of large edits, all of your edits will still be fully recorded. These size limits are only rarely encountered. The reverted version of your file presented in “$tempStdOut” will not retain any markers or illustrations from the original. Normally, markers can be easily replaced with the Automark command. To reinstate illustrations, you’ll need to use your resource editor to copy the appropriate PICT’s. > How to revert a file If your circumstances meet the above conditions, you can revert a file (still called “A”) by following these steps: •1 Open an EnterAct project (any will do) •2 If necessary, add file A to it •3 Select "Show Activities..."; click on the "originally recorded positions" button; and for the number of activities to show, enter "10240"; and click the OK button to generate the "••Recent Activities••" window •4 Locate the oldest activity you wish undone, and note its activity number -- this appears just afer the "¶" beginning the activity record, for example "¶314" •5 Save "••Recent Activities••" somewhere - NOTE the name must start with two bullets, but is otherwise arbitrary, for example, "••RA" or "••For undo". The bullet character is <Option><eight>. •6 Add your saved version of "••Recent Activities••" to your project, then close the window for "••Recent Activities••" to save memory •7 Select both the saved version of "••Recent Activities••" and file A for MFS operations, by holding down the <Option> key and clicking on each name in the project window - a bullet • will appear beside the file name). These two should be the only files marked with a • in your project window •8 Call up hAWK and select the supplied program “$Multi_Undo”; the input option should be "MFS selected files"; use "Set Variables" to set the value of the variable "howFarBack" to the activity number that represents how far back (inclusive) you wish to undo. For example, howFarBack=314 to undo from the present (the largest activity number) back to and including activity number 314. •9 Click the Run button. The undone version of file A will (eventually) be presented in the "$tempStdOut" window. You can continue working in EnterAct in the meantime. •10 Save "$tempStdOut" under a different name if you wish to keep the results (see “Preserving the undone version” just below for an explanation) •11 If there are other files you wish to restore, add them to your project if necessary, open your saved version of "••Recent Activities••" to determine how far back to undo, then close it and repeat steps 7-10 (especially step 10). While you're waiting for $Multi_Undo to finish you should avoid editing either file A or your saved version of "••Recent Activities••". For more information on running hAWK programs see the “hAWK User’s Manual” supplied on disk. > Preserving the undone version The “$Multi_Undo” program stops one step short of actually reverting your file, in that the reverted version is contained in the file “$tempStdOut” at the end, rather than immediately replacing the contents of your file. If you decide to keep the reverted version, you can use Save As on “$tempStdOut” to create a permanent copy of the reverted file. You should do this before your next hAWK or Read Resource run, because the file “$tempStdOut”, as its name suggests, is overwritten with every Drag_on Module run. If you use Save As to replace your file A with the reverted version, this will not be undoable, and the unreverted version will be lost. If you’re not absolutely sure that the reverted version should replace the unreverted version, it’s best to give the reverted version a name name that is close to the old one (eg the reverted version of “MyEvent.c” could be called “MyEvent2.c” or “MyEvent_r1.c” etc). § Turning activity recording on and off > Temporarily When activities are being recorded you will see a menu item named Recording activities under the Edit menu: it will change to read Not recording activities if you select it, indicating that recording is turned off. Selecting it again will turn recording back on. Even if you are not recording activities, EnterAct will still open the log file “EnterAct Recent Activities” each time you start EnterAct, creating it if it is not found. And you will still be able to Show Activities. Turning activity recording off temporarily is rarely useful. However, you might consider it if you are about to perform a number of trivial changes, or very large edits that you don’t need recorded, and want to preserve the current record of your activities as much as possible. But if you are aware that vitally important data exists only in your recorded activities, it would be better to Show Activities and Save the resulting activity list to disk, to avoid losing the data as older activities are dropped from the log file. > More permanently The “master switch” for EnterAct’s activity recording is in the Options dialog (under the Edit menu). You may wish to forego the recording of your activities if you don’t have enough disk space available to hold the log file (2.1Meg), or if your hard disk makes so much noise that you can’t work when it’s active. To turn off activity recording, and also instruct EnterAct not to look for or create the “EnterAct Recent Activities” log file, uncheck the “Save activities to disk” option in the Options dialog and click the OK button: as you do so, the icon of the log file will be crossed out, indicating that the file will no longer be needed or used. You may then dispose of the log file if you wish, and EnterAct will not complain. To reactivate activity recording, check the “Save activities to disk” option in the Options dialog and click OK. A log file will immediately be created if one does not exist at the time. If the log file exists, recording will pick up again with no loss of previously recorded activities. - - - - - - - - - - - - “Index” commands - - - - - - - - - - - - PLEASE NOTE the index commands "Functions", "Cross-Reference", "Potential Locals" and "Check Prototypes" are intended for use with C code only (not C++ or Java). The “Index” commands under the EnterAct menu generate a variety of reports on your source code. With all except the Potential Locals and Check Prototypes command, set up a multi-file selection first to serve as input for the command. Potential Locals takes a function body with parameters as input. Check Prototypes looks at all of the function definitions and prototypes in your entire project. All output from these commands is to $tempStdOut. Functions… builds a list of functions in your selected files: it can list functions defined in the files together with sublists of the functions that each defined function calls, or conversely you can have a list of all the functions called in your source code, together with sublists showing which functions call them. Cross-Reference… generates a cross-reference listing: you can specify the types of term (function, struct, variable etc) to include, the specific terms to look for (your current dictionary), and the files to look in (your current multi-file selection). Supporting doc files in your rightmost project pane can be included in the cross-reference. You can also specify a list of common words (such as Handle) to skip for cross-reference purposes. #Includes and Marker Names generate lists of system or user headers, and marker names in a variety of formats, in your selected files. Potential Locals classifies and lists all terms in a function. Just before this command, select the entire body of the function and the parameters (ie from the opening ‘(’ of the parameters to the closing ‘}’ of the function, inclusive). In the resulting list, names that have no definition and are not parameters, and hence are probably local variables, are listed first. The number of times each name was used is also listed, and by comparing this list with your original function you can quickly declare all necessary variables or eliminate unnecessary declarations, and also spot spelling mistakes. Standard Metrics issues counts of lines and characters in selected files, and also shows character frequencies. Check Prototypes is rather primitive, catching only a difference in the number of parameters to a function. No need to bullet any files, just bring your dictionary up to date beforehand. It's intended for use with C source only, not C++ or Java. § Functions… For use with C source only. This command can be used to build a “skeleton” for selected source files, a bare list of functions defined together with the functions they call. It also works in reverse, and can be used to list all functions that are called, together with sublists of the functions that call them. Input is taken from your list of files selected for multi-file operations (use the Find dialog buttons, or <Option>click in the project window, see the “Search” chapter). Only files in the left and middle project window panes will be looked at, and any files you select in the right (documentation) pane will be ignored. You’ll see results in “$tempStdOut”: if you decide you want to save the results permanently, use Save As to save this document under a new name of your choice, since the contents of $tempStdOut are overwritten by every Index command or Drag_on Module run. For proper results, your dictionary should be reasonably up to date before using this command. In particular, your dictionary should contain entries for all functions that you wish to see listed. For example, in order for toolbox functions to show up in the listing you’ll need to add the appropriate toolbox headers to your project and update your dictionary. When you select “with calls” in the Functions dialog, the main list in the result will consist of functions defined in your list of source files. Indented under each defined function will be a list of functions called by the defined function. If you select “as defined” then function definitions will be listed in the order encountered in your source files, with a comment containing the file name beginning each list for each file: If you select "sorted” then all of the function definitions from all files will be sorted alphabetically. In this case you can select “include file locations” to list the defining file for each function: If you select “with callers” the resulting list will show all functions that are called in your source code, with an indented sublist for each naming the functions that call it. Here also, if you select “include file locations” then the defining file name will be listed with each function name. With any function name, you can jump to the definition for it by <Option> double-clicking on the name. File names in the listings are enclosed in «» quotes: to open a file, click anywhere on the line containing the file name and issue a “Go to”. § Cross-Reference… For use with C source only. The Cross-Reference command generates a cross-reference for all term types you select, in all files selected for multi-file operations. Names are listed in alphabetical order, with a sublist for each name listing file name and line number for each instance, and optionally the name of the function containing the instance. Only names that are defined in your current project dictionary will be included in the listing. Note that you can cross-reference supporting documents with this command, by putting a bullet (•) beside the name of each supporting document. The “include containing function names” option will be ignored for support docs. To generate a cross-reference just for names that are defined in certain files, rather than all names defined in your current dictionary • make a new project, and add to it only those source and header files which contain functions, variables, structs etc to be included in the cross-reference • use Update Dictionary to build a dictionary for just those names • add any additional files to be cross-referenced to your project • place bullets (•) beside the names of all files you want to cross-reference • select Cross-Reference • optionally specify a file containing a list of common words to skip, with the “Skip words in…” button • specify the term types (function, variable etc) to be included in the cross-reference, or click the “All types” button • click OK and your desired list will appear in the $tempStdOut window Normally your current project dictionary will be the appropriate one to use for cross-referencing, and you won’t need to make a new project just for this purpose. As with all Index commands, use Save As to save $tempStdOut under a different name if you decide to keep the results—$tempStdOut will be overwritten by your next Index command or hAWK run. The “Skip words in…” button in the Cross-Reference dialog allows you to specify a list of words to skip, typically common names such as OK, Handle, DialogPtr that you aren’t interested in. The names in the file can appear in any order, and can be separated from one another by spaces or <Return>’s. The file “Skip for XRef” which comes with EnterAct contains a starter list. You’ll find it in the “hAWK Programs” folder, which is inside the “Drag_on Modules” folder inside your development folder. To cancel the use of a skip-list, click the “Skip none” button. When you select “include containing function names” the name of the function, if any, containing each reference will be shown to the right of each reference. Names which occur outside of a function body, including all names encountered in support documents, will not have a containing function listed. The format of each reference such as ____ «AssocArray.c» 260 SetArrayValue ____ is «file name» line-number containing-function (if any). To go to a particular reference, click on the reference line and use “Go to”. To jump to the definition of a containing function, <Option> double-click on its name. § #Includes… To list header files that are included in one or more source or header files: • select the source and header files for multi-file operations • select the #Includes… command • pick either system headers with the <headers> button, or project-specific headers with the “headers” button, or both • click OK, and the list will appear in the $tempStdOut window • use Save As on $tempStdOut to make a permanent copy of the results. Included file names are listed in the order encountered, together with line number. § Marker Names… To list the names of all markers in one or more files: • select the files (any panes) for multi-file operations • select the Marker Names… command • pick your preferred format for the names • click OK, and the list will appear in the $tempStdOut window • use Save As on $tempStdOut to make a permanent copy of the results. The «file-name»«marker-name» format is useful for establishing “go to” links, as explained in the “‘Go’ commands” chapter. The other two formats can also be used as “go to” links, but work only within the file that contains the marker. EnterAct's default behavior is to NOT save marks with source or header files, so there will normally be no marks listed for these files. In practise you will probably not need special “go to” links for functions or structs anyway, since <Option>double-clicking on the name anywhere will take you to the definition. “Go to” links are intended mainly for establishing hyperlinks to documentation files (this manual is already redundant enuff, so please see chapter 17 for details on creating and using «file-name»«marker-name» links). § Potential Locals For use with C source only. This command helps with the declaration of local variables. To use it, first select the parameters and body of a function, from the opening parenthesis of the parameters to the closing curly brace of the function body, inclusive, as shown above left. Then select Potential Locals:results will be shown in $tempStdOut. Names are shown three per line, each followed by the number of times the name was encountered in the function. The first list, “These look most like locals:”, consists of those names seen in the function which have no entries in your current dictionary, and hence they are the best candidates to be local variables. Note, though, that they could also be goto labels, or names that for some reason are not defined in your dictionary. Names in this list with a frequency of 1 bear a close look—often they have been used but not declared, or declared but not used, or the name has a typo. Names in the other lists might also need declaration as local variables, if you have used the same name for a local and something else (such as a global variable, typically). § Standard Metrics This command reports the total lines and characters in each of your files selected for multi-file operations, followed by a C-style array listing the number of times each character was seen. Comment characters and lines are included in the totals, but blank lines at the end of a file aren’t counted as lines. § Check Prototypes For use with C source only. This command checks all of the function definitions and prototypes in your project dictionary, checking ONLY the number of parameters for each function. It reports the names of any functions that are declared with different numbers of parameters. Before calling this command, you should bring your dictionary up to date with Update Dictionary for best results. There is no need to select any files for multi-file operations when using this command. You just need a project open with a built dictionary. This is a primitive version, and catches only differences in the NUMBER of parameters to a function. And it's only for C files, not C++ or Java. Don't trust it to validate prototypes, use it only to spot the particular problem of the same-named C function having a different number of parameters in variant declarations. This typically happens when you change the definition of a function and forget to change a prototype for it in a different file. If no prototypes are shown in stdout, your function definitions and declarations all had a consistent number of parameters. Or arguments, if you prefer. I won't argue. - - - - - - - - - - - - Some thoughts on using EnterAct - - - - - - - - - - - - (Worth mentioning again, EnterAct can be used as just a "definition viewer" to help out other editors -- see the end of "Lookup", chapter 10) (As of September 95, the advice below about how to avoid lookup delays and minimize memory use is sounding a bit dated; however, it's still true that smaller projects are easier to manage.) § Projects are cheap EnterAct projects are quick and easy to create, the only real penalty being the amount of disk space used. While an EnterAct project can be truly enormous and still be usable, lookup will be faster and more appropriate if you tailor your project to the problem at hand. As an extreme example, here’s a generic project that would be perfectly suitable for developing file–handling functions: Lookup in this size project will always be instantaneous no matter how bad your spelling, and lookup for your terms will never be confused by accidental matches against terms in files that you don’t need reference to. While accidental matches are not common, the speed of lookup when your spelling is not exact does depend directly on the size of your dictionary. At the other extreme, you can create projects with files from more that one application/driver etc. This can be very handy for comparing different versions or different approaches to a problem. In practise, the main penalty comes when you want to jump to a particular definition, and there's more than one: to choose the one you want, you have to press <Enter> to look it up and then <Option>double-click in the lookup window. The rule of thumb then is that an EnterAct project can consist of whatever files you want, but performance will be better if you don’t add files that you don’t need. There is a tradeoff between having absolutely everything of potential interest in a large, complicated project, and having several smaller but better–performing projects. For ultra-compact project backup, in the event that some of your projects are tedious to create: • select all of the files in your project for multi-file ops, by clicking the "All" button in the Find dialog • select hAWK from the EnterAct menu, and select and run the program "$EchoFullPathNames" • use Save As on the resulting stdout window to save your list of project files • to recreate your project: create a New Project; hold down the <Shift> key while selecting "Add Files..." (the menu text will read "Add Files from List...") and select your text file of full path names in the subsequent Open dialog; and bring your dictionary up to date after the files are added. § Learning from or reviewing code If your purpose is to explore rather than create, then you won’t be typing in many incorrect spellings. Lookup when spelling is correct is always instant, which is the case if you’re just reading through code and looking up terms in the code as you go. In this case the only restrictions on the size of the project are the amount of disk space and RAM needed, and you can add absolutely all files related to the application without slowing down the lookup. (Strictly speaking, lookup is instant only for terms with entries in your dictionary. Specifically, struct and class member names are not separately entered in your dictionary, and it can take a second or more for the AutoLook window to pull up a definition that contains the member name. Sorry, there's no plan to speed up member lookup. Member lookup won't hang you up, it will just be stopped if you start typing or mousing around during the search.) § On documenting your work There is little in this manual on the topic of documentation, primarily because it’s up to you how, and how much, you document your work in separate files. But it’s worth mentioning that EnterAct has a variety of features to help you create and maintain your documentation. Here’s a list: • documentation files can be added to the rightmost pane of your project, for regular double-click access just like source and header files • <Option> double-click or Find Definition can be used on any term that appears in your documentation to jump to its definition (provided of course that your dictionary is reasonably up-to-date) • the AutoLook window will instantly update to display definitions of terms in your documentation (double-click on the term or click just after it). And clicking after a term and pressing the <Enter> key will produce a more persistent separate lookup window • your own notes on various programming topics can be “disguised” as C terms, and in this form they can be built into your project dictionary for instant retrieval to the AutoLook window or a separate lookup window wherever the name of the note appears (see “Looking up your notes” in the “Lookup” chapter) • “Go to” accepts file name followed by marker name, as explained in the “‘Go’ commands” chapter. These look like /* See «MY OOP Notes» «Static variables» */ and the text for them can be generated by picking the marker from the popup menu in the document where it is defined while holding down the <Shift> key as well as the usual <Option> or <Command> key. The link location is maintained as you edit, since the marker’s location is maintained, and if the file and marker names are in «» quotes they can be abbreviated or even slightly incorrect and still work. • “Go to” also accepts file-name and/or line-number selections. Text for this style of “go to” link is generated by the Show Activities command, and by a variety of supplied hAWK programs. For an example of line numbers used to index a document, see the “Active Index” at the bottom of the “hAWK User’s Manual” on disk 2. • Reformat Selection can be used to even up the lines in one or more paragraphs of your documentation • if you have any relevant PICT files, you can add them to your project for quick access. And “Go to” accepts PICT file names. You can also add one or more PICT’s as illustrations in a TEXT document (see “Illustrating your text” in the “Editing” chapter). • the hAWK program "$CompareFiles" can be run on any two of your project files to list differences. EnterAct can track and link all of your supporting documentation. If you develop naming conventions for your documents, and make use of some of EnterAct’s linking power, you should find it’s a lot easier to keep track of things. References will be just a double-click or “Go to” away, which beats shuffling through a stack of papers or calling up an accessory outliner all to heck (pardon the enthusiasm). - - - - - - - - - - - - If there’s a problem - - - - - - - - - - - - § Out of memory If you run out of memory while trying to do something, you’ll see an Alert saying “Out of memory. Please close up and try again when things are less busy.” or the equivalent. Open windows take up memory that you can free by closing the window The project especially can take a lot of memory (Megabytes), since the entire dictionary associated with it is kept in memory. If you encounter frequent “Out of memory” messages, the least inconvenient but most expensive cure is to allow more memory for EnterAct, which may involve buying some chips. However, you can often free up a considerable amount of memory by removing relatively unneeded files from your project. The rough rule is that your project dictionary will take up in memory about one–half of the disk space used by all .c and .h files in the project (a better estimate, 16% of source files plus 120% of header files). If you don’t need lookup for any of the terms in a .c or .h file, removing it from your project will free up some memory. Note that plain text files in the rightmost pane do not greatly affect memory used, since they are not incorporated into the dictionary. To see how much memory is free at any time, select Show Activities from the Edit menu. At the bottom of the resulting dialog you will see the amount of memory currently available. Or you can use "About This Macintosh..." in the Finder, turn Balloon Help on, and point your mouse at EnterAct in the dialog. For a guide to estimating memory needs and trimming unneeded files from your project, see the file “EnterAct memory needs”. § Dictionary problems > Missing dictionary entries In rare cases, an error in your source may lead to a term not being recorded in your dictionary, with no message. An example is ____ int x /* missing semicolon */ long y; ____ for which EnterAct would record only the “y”, missing the “x”. This is the one time that EnterAct’s tolerance of errors can be a nuisance, but if you can remember where the term is defined then visual inspection should reveal the error, typically a missing semicolon or a missing or misspelled keyword. If you can’t remember where the term is defined, and you really want lookup to be available for it, then the one sure cure is to switch to THINK C and Compile or Check Syntax until you spot and fix the bug. > Trouble building your dictionary If the dictionary–builder trips over a bug in your code and you can’t spot the problem after reading this section and examining your code, your next best course of action is to switch to THINK C and compile the offending file. If you call for technical support and your code is not compilable, there is only a small chance we can help, since the possibilities would be too open–ended. Look on the bright side, you’ll have to compile your code sooner or later anyway. EnterAct sets moderately strict standards for the part of your code that is outside of a function, struct, or union body. However, code that is inside of a function, struct, or union body is primarily checked only for proper balance in a few key delimiters, typically {}, (), and /* */. As a result, almost all of your first–draft errors will be simply ignored. Some errors outside of a body can be compensated for, and the remainder that do trigger a complaint from the dictionary–builder will almost always be fairly obvious. Here follows a complete list of the messages you might see after selecting Update Dictionary or Update For Front File Only. ____ "Statement too complex to deal with all at once. Any chance you could simplify?" ____ This message should be rather rare. You would have to nest brackets more than 200 deep, or have more than 256 enum constants in a single enum in order to produce it. I’m not giving an example! The cure would be to reduce the number of brackets in your deeply–nested construction, or split a monstrous enum into two parts. ____ "Typedef cannot have an init. One or the other has to go." typedef int SHORT = 7; ____ This should prove rare. “typedef” essentially creates a new keyword, and you can no more initialize it than you could initialize “int” itself. Apologies for stating the obvious. ____ "Illegal word or punctuation after struct or union." struct int myStruct {... /* int */ struct /myStruct {... /* the '/' */ struct myStruct (...} /* wrong bracket */ ____ Something between “struct” or “union” and the opening left brace (if any) of the body doesn’t belong. Or, you may have neglected to type in a name for the struct or union. ____ "Illegal word or punctuation after enum." enum Numbers int {... /* int */ enum /Numbers {... /* the '/' */ enum Numbers {one two three}; /* missing commas */ enum Numbers {one, two; three}; /* that first semicolon */ ____ Includes all the sorts of errors for a “struct” or “union”, and also any error inside the body of the enum where the enum constants are listed. EnterAct does not record any terms inside a struct or union, but does record all enum constants, hence checking for an enum is more strict. Some errors (such as an extra comma) can be shrugged off, but most others will trigger this message. ____ "#if has no matching #endif, #else, or #elif." ____ I’m afraid you’re on your own tracking this error down, since it could be anywhere in the file after the position shown. It could be due to a misspelling, such as #eles, or the necessary “if–ender” could be missing altogether. ____ "Function(?) has no name." long (int x, char *tPtr); ____ So, give the poor function a name. ____ "Pascal must be followed by a function." ____ “Pascal” or “pascal” indicates that a function passes arguments and returns a value according to Pascal rather than C conventions. For more on this topic, see your THINK C manual. ____ "Couldn't find end of initialization." struct MyStruct {int x; long y} instance = {4, 7L; ____ Typically this is caused by a missing or extra '}', as in the above example. It could also be caused by a missing semicolon. ____ "Unbalanced statement. Use the Balance command right after OK'ing this alert to diagnose the problem." ____ Since the Balance command checks all delimiters and shows you at least one end of an unbalanced construction, finding the typo that caused the lack of balance is usually straightforward. Selecting Balance a second time can be useful—after the second Balance either you’ll be shown a mismatch for the first delimiter or you’ll hear a beep indicating that the other end is completely missing. ____ "Unbalanced or nested comment. Use the Balance command right after OK'ing this alert to diagnose the problem." ____ EnterAct’s comment checking while dictionary–building (and balancing) is even stricter than most compilers. For details, see the “Nested and bad comments” section in the “Balance” chapter. As a byproduct of dictionary–building, all source files in your project will be thoroughly checked for comment errors. If the problem is due to consecutive comment starts, and you want to keep them because that’s the way you do things, select Options from the Edit menu and uncheck the “Detect nested comment starts” check box. This will partially disable EnterAct’s ability to trap comment problems, both when building your dictionary and when balancing. ____ "Lack of balance in parentheses (). Use the Balance command right after OK'ing this alert to diagnose the problem." ____ See above, Unbalanced statement.... ____ "Unbalanced single or double quotes. Use the Balance command right after OK'ing this alert to diagnose the problem." ____ See above, Unbalanced statement.... ____ "Unbalanced square brackets []. Use the Balance command right after OK'ing this alert to diagnose the problem." ____ See above, Unbalanced statement.... ____ "Left curly brace { is not preceded by struct, union, enum, =, or function definition." typedef stork MyStruct {int x; long y};/* stork?struct? */ long ShouldBeFunction{int x, long y); /* '{' vs '(' */ ____ Either the '{' should be something else, such as a '(', or a keyword just before the '{' is missing or badly misspelled. EnterAct can handle some typo’s, such as typdef sturct... but at some point (such as twerpdeaf stork) has to give up and complain. ____ "Colon must signal class name, method name, or low-memory global." ____ Note this exludes some uses of the colon which are irrelevant for dictionary–building, such as bit fields and any usage inside a function body. ____ "Something is wrong at or near the position shown. Sorry, if you can't fix the problem please email tech support." ____ A Shakespearean sonnet will trigger this message. In general, the error lies outside of EnterAct’s area of competence. Check for typo’s at or near the position shown in the file. This message corresponds to the “Syntax error” message that compilers issue when they give up and don’t have a clue what’s going on. My favourite way to generate this error is to accidentally add a junk file with a name ending in .c or .h to a project. A reminder, Add All In Folder inhales every text file in a folder. This message can also be triggered by a preprocessor conditional that's too tough for EnterAct to handle without your help -- see "DON’T GIVE UP" near line 108 in this file, and also "Source code restrictions", chapter 7, for the details. The symptom here is often that the indicated error position is within a function body, an unusual case because EnterAct's parser does almost nothing with function bodies except check them for balance -- this means the parser ran past the start of the function without seeing it. If you spot the usage of a macro just above the function, and the usage does not end with a semicolon, try entering the name of the macro in the "Macro's to skip..." dialog. This usually fixes the problem. ____ "Function body was expected but not found at the position shown." ____ This typically results from a missing left brace '{' at the start of a function. Rarely, it can be caused by an excess semicolon in an “old–fashioned” style function definition, between the list of arguments in round brackets and the start of the function body, eg: ____ int myFunc(x,y) int x; long y;; /* extra semicolon */ {...} ____ The dictionary–builder counts up your arguments, and won’t allow more semicolons than you have arguments. § Lookup problems For background, here’s a list of common errors that may throw regular lookup off: •1 using a synonym •2 full spelling when a nonstandard abbreviation is wanted •3 use of an abbreviation when fuller spelling is wanted •4 full spelling when a standard abbreviation is wanted •5 case error •6 permutation of the words in a name •7 typo •8 spurious extra character •9 homonym (sounds the same, spelled differently) •10 missing definition, due to an error in the source or source file not included etc Regular lookup can compensate for the more popular single instances of 1-3 above with the lookup table of alternate spellings that you’ll find in EnterAct’s 'TEXT' 1000 resource. Single instances of 4-5 are thoroughly checked (see next page for the definition of a standard abbreviation). An instance of error 6 is also caught, provided there are at most four words making up the name. For all other errors (7-10, or combinations of errors) EnterAct exhaustively checks what you’ve typed against all dictionary entries, totalling up runs of matching characters and showing the best matches. If the definition is just plain missing, there’s not much that EnterAct can do to help. “Sounds like” lookup is extremely error-tolerant, including being case-insensitive, at the expense of ignoring some of the information (mainly vowels and case) in what you type. It does do the fast checks for errors 1-6 above, in the same way as regular lookup. On average it’s less accurate than regular lookup, but useful as a last resort. Reverse lookup tolerates only case errors, being case-insensitive; otherwise, your spelling must be exact (current machines are too slow for error-tolerant reverse lookup, and in any case it would be too hyperactivated). > Memory failure (yours, that is) The term is in your dictionary but you can’t remember the spelling well enough to retrieve it? Here are some guidelines to follow: • Nearly every name in your dictionary will have some distinctive part that uniquely identifies it, both from your point of view and EnterAct’s. Spell the distinctive part right, and you’ve got it. • If a name consists entirely of common words (Handle, Get, etc) you’ll have to spell more of the name correctly to help EnterAct distinguish among the possibilities. • If in doubt, spell it out. If there’s no exact match, EnterAct will try all standard abbreviations of each of the words in the name. • When you abbreviate part of a name in your source code, try to follow one of these standard abbreviation rules: 1) starting from the end of a word, drop vowels, and when all vowels are gone start over at the end and drop consonants; 2) truncate the word without regard for vowels; 3) either of the above rules, but keep the last letter of the word. If you follow any of these rules and leave at least 3 characters in the abbreviation then EnterAct will be able to generate the abbreviation from the full spelling, producing instant lookup (eg commandKey will retrieve cmdKey, by applying rule 1 but keeping the last letter of command). • If lookup for the name is immediate but wrong, add a spurious uncommon character at the beginning of the name and try again (if name doesn’t work try zname or xname to force a full search). • Use the Options dialog to increase the number of entries kept per lookup window to 10 or more, and try again. • A single case error will be shrugged off, but otherwise regular lookup is case–sensitive (eg CmdKey or cmdkey will retrieve cmdKey immediately, but CMdKey or CMDKey won’t). If you think you have several case errors, try “sounds like” (<Option><Enter>) lookup instead of regular lookup. > Lookup fails You know the term should be in your dictionary but even typing its exact name doesn’t retrieve it? This is rare, and is caused by EnterAct misinterpreting an error in your source code. Looking at the statement where the term is defined or mentioned in your source code will usually reveal a simple error such as a missing semicolon or a misspelled keyword. If not, switch to your compiler and compile your code until you’ve cleared any bugs in the statement where the term occurs. > Miscellaneous lookup problems In the rare case that your dictionary is small and the name you type doesn’t match any term in the dictionary to any reasonable extent, you’ll just hear a beep and no lookup will appear. The hint for #defined macros is the same as the hint for other #defines—add a '#' after the name, rather than a '('. In general, if the lookup you see is not what you wanted and you supplied a one–character hint, try again without the hint. Looking up classes and methods is discussed in more detail in the “Browsing” chapter. If you suspect your spelling may be way off, try increasing the “Number of entries per lookup window” in the Options dialog to 10 or more, and then try the lookup again. If you’re quite sure that a term should be in your dictionary but it doesn’t appear when you look it up, take a look at the statement where the term is defined or mentioned: you could have accidentally violated a required coding convention (unlikely), or you could have a succession of first–draft errors that has confused EnterAct. A missing semicolon or misspelled keyword can sometimes result in a term being skipped. If you employ macro’s to do such things as optionally include or omit full prototypes, or typedef’s, then you should register them with EnterAct using the Macro's to skip command, as described in the “Source code restrictions” chapter. If you run into a problem that stumps you, please compile your code before calling for help. However, if you end up fixing bugs in your code that you feel EnterAct should have been able to tolerate, please call and let me know. kearle@interlog.com. § Editing problems EnterAct has a single level of undo, and the window that the undo applies to must be in front in order for the Undo command to be enabled. To undo a Paste Selection Behind, the window pasted into must be in front, and the window copied from must be just beneath, the way EnterAct leaves them after carrying out the command. If you can remember which two windows were involved in the Paste Selection Behind, just bring them to the front alternately until the Undo is enabled. If Paste doesn’t preserve your indentation, it’s because you’re leaving some text at the left of the first line unselected when you select a range or insertion point for the Paste. In particular, Paste won’t preserve indentation if you select an insertion point for the Paste that is to the right of the first visible character on the line (“visible character” here meaning something that is not a space or tab). While we’re on the subject, you can switch off the preservation of indentation for a Paste by typing a single character just before you Paste, and then deleting it after. § Balance problems If lack of balance is caused by mismatched delimiters, such as '{' matched against ']', then by repeatedly selecting Balance you can toggle between the two mismatched delimiters. If the unbalance is due to a missing delimiter, keep in mind that EnterAct handles comments properly, so the error will not be due to an extra delimiter inside a comment. For example, a comment such as ____ /* 1) load 2) decrement 3) store */ ____ won’t trigger an error, unless you start with an insertion point or selection that is inside the comment. If you’re attempting to balance a closing delimiter and Balance has to run backwards through an “asm {..}” block while searching for the matching opener, you might get a spurious error due to something in an assembly–language comment—see the “Balance” chapter in “The asm problem” section for details. If the problem is due to consecutive comment starts, and you want to keep them because that’s the way you do things, select Options from the Edit menu and uncheck the “Detect nested comment starts” check box. This will partially disable EnterAct’s ability to trap comment problems, both when building your dictionary and when balancing. When you Balance an entire file, you will hear a beep whether or not the file balanced, just to tell you that the balancing is finished. If the cursor doesn’t move from the top of the file, that means the entire file is balanced. If there is any error in the file, you will be shown the first unbalanced delimiter. When balancing just part of a file, you will hear a beep only if there is an error. Otherwise, the selection range will quietly expand to the next largest balanced range. If there is no larger enclosing range (this is the case when you start with an entire function body selected, for example) you’ll hear a beep but the selection range will not change With the exception of strings, only two types of balance errors can occur; mismatched ends, and missing ends. If Balance beeps and shows you an unbalanced delimiter, try immediately selecting Balance again. Then, if the problem is due to mismatched delimiters, you will be shown the other end. If the problem is a missing end, nothing new will happen—you’ll hear another beep, but the selected delimiter will not change. Strings in double quotes " " are checked for one additional special error, a missing backslash if the string is continued across lines. The backslash must be the very last character on the continued line, just before the <Return>—note that even a space before the <Return> will “hide” the backslash. Personally, I don’t think this is reasonable, but that’s the way C is. - - - - - - - - - - - - License agreement, tech support - - - - - - - - - - - - § Technical support You can reach me (Ken Earle) at: ____ kearle@interlog.com via InterNet. INTERNET:kearle@interlog.com via CompuServe, or via real-mail at: Ken Earle 697 Spadina Ave Toronto, Ont Canada M5S 2J1 ____ (reply will be by e-mail, so please include an email address). § License By using EnterAct, you are agreeing to abide by the terms of this license. If you disagree, don't use it. If you agree, send money, then come to disagree and want your money back—well heck, everybody makes mistakes now and then, just let me know what the problem is and you'll get your refund. Do so within 60 days though, else I may deem that EnterAct in your hands has already paid for itself several times over. This version of EnterAct carries a charge of zero dollars and zero cents Canadian, so sending that in is optional. Site licence discounts are available. Neither Apple Computer, Inc., nor any other company makes any warranties, either express or implied, regarding the enclosed computer software, its merchantibility, or its fitness for any particular purpose. The exclusion of implied warranties is not permitted by some governments. The above exclusion may not apply to you. This warranty provides you with specific legal rights. There may be other rights that you may have which vary according to location. EnterAct and this manual are copyrighted, with all rights reserved. You may distribute full copies of EnterAct (omitting no files from the compressed archive that comprises EnterAct), provided you do not charge for EnterAct itself. In no event shall Dynabyte or any other legal entity involved in the creation, production, or delivery of this product be liable for any direct, indirect, consequential, or incidental damages (including loss of data, lost business profits, business interruption, carpal tunnel syndrome, and the like) arising out of the use of or inability to use the software or accompanying material. EnterAct does not support shared file access. If you use EnterAct on a network, or as a member of a team working on the same source, be aware that EnterAct will allow two or more people to open one file with full read/write access. You must use some separate form of source code control to avoid losing or accidentally generating variant versions of files. I have done this, by the way, with SourceServer, and everything worked fine. This agreement will be governed by the laws of the Province of Ontario "hAWK", "Read Resource", their associated source code and manuals, and the Drag_on Modules interface are yours to keep, free, no matter what. They are governed by the Free Software Foundation's "copyleft", as described in the document "copying hAWK", included with your EnterAct package. - - - - - - - - - - - - Appendix 1 Drag_on Modules - - - - - - - - - - - - Drag_on Modules resemble HyperCard XCMD’s and MPW tools in that they are separately–compiled chunks of code that are designed to be called from within some application. The calling application is at liberty to provide any of a dozen or so callback functions, which mainly enhance text–oriented communication between the calling application and Drag_on Modules, but these are all optional. The calling interface has been kept simple, so that if you have an application written in C or C++ you can add to it the ability to call Drag_on Modules without hurting yourself—a day or two should do it. Instructions for doing so can be found towards the end of the “hAWK User’s Manual” and in the file “Call_Resource.c”. The source code for “Minimal App7" illustrates the basic process. As far as the callback functions go, if your application deals with TEXT documents you’ll be able to support most of them easily, and if you can’t support one then the Drag_on Modules will get along without it. The idea behind Drag_on Modules is to provide a medium for the inexpensive modular distribution of source code that works best when it is allowed to interact with full applications. Drag_on Modules could easily be repackaged as separate applications, but then the interaction with other applications would be slower. In the absence of a universal “shell”, the next–best solution offered by Drag_on Modules and the like is to let each application be a shell. Admittedly, System 7 has promise as a universal application coordinator, but while we’re waiting it’s nice to be able to achieve the same effect with just 2K of overhead per application and the extreme simplicity of file–based communication for major input and output. To help the illusion that there is a shell lurking in the background, Drag_on Modules communicate by means of standard input, output, and error files. This allows results from one Drag_on Module run to be passed as input to a subsequent run, for example. Two Drag_on Modules are currently being shipped, hAWK and Read Resource. Read Resource is just a simple resource or data fork viewer. hAWK is a Mac implementation of AWK. You may have seen above that hAWK has a "three clicks and Run" interface, and it's true: for example, you could select hundreds of file as input to a hAWK program by putting bullets beside them in your project window, and then to call up the program: select "hAWK" from the EnterAct menu; pick your program from the top popup; optionally adjust the input option (all or part of the front file, MFS-selected (ie bulleted) files, or a specific file -- this option can be saved with the program, so normally there is no need to change it); and then click Run. The program will run in the background as you continue to work with EnterAct. Added for version 3, you can now write hAWK programs that watch EnterAct's clipboard, and, when your specified conditions are met, write anything you like back to the clipboard. This gives you in effect a "magic clipboard", ideal for reducing repetitive, moderately complicated tasks to a simple Copy and Paste. For details see the separate document "EnterAct's magic clipboard". And in version 3.6, a hAWK program can be invoked by placing a command line for the program in any EnterAct text window and then pressing <enter> or <command><return> with the command line selected. For an example, see "§ Code templates" in the Editing chapter above. For details, see "Appendix 2 Calling hAWK programs" just below. Drag_on Modules come with complete source code. Complete code and instructions for calling Drag_on Modules from your own application can be found in the file “Call_Resource.c”, as supplemented by the example of “Minimal App7". If you are interested in creating your own Drag_on Module, please see the “write your own Drag_on” folder. - - - - - - - - - - - - - - - - Appendix 2 Calling hAWK programs - - - - - - - - - - - - - - - - hAWK programs can be called via a dialog, by picking "hAWK" from the EnterAct menu, or by entering a command line in any text window. The "hAWK User's Manual" explains how to write hAWK programs, and also how to run programs via the dialog. If you like the idea of being a power EnterAct user, the section below called "Calling hAWK with a command line" will have you firing off hAWK programs by typing a few characters. § Calling hAWK from the menu EnterAct follows the procedure described in the hAWK User's Manual, in the chapter "Running hAWK programs". The "MFS selected files" input option corresponds to the bulleted text files in your current EnterAct project (you can put bullets (•) beside project file names by using the buttons in the Find dialog, or by <option>dragging in the project window). Your hAWK program will run in the background by default, so you can continue working in EnterAct while running a lengthy program. If you're using EnterAct to view this and have installed the Drag_on Modules folder, give hAWK a try right now: • put some bullets beside some file names in your project window (if you don't have a project yet, please read at least "EnterAct in brief" to get going) • select "hAWK" from the EnterAct menu • pick the program "$EchoFullPathNames" from the top popup menu in the resulting setup dialog • click the Run button • the stdout window will appear after a couple of seconds, holding a list of the full path names for your selected project files. If you're intrigued, please see the hAWK User's Manual for details. § Calling hAWK with a command line If you need to regularly run a hAWK program, and it doesn't take its input from the front text window, you might find it handier to run it with a command line. Command lines aren't too nasty to construct, and you'll only have to do it once for each program if you create a code template for the command line. There are examples below, and it really is fairly easy. You can enter a hAWK command line in any text window. To run it, select the entire command line and press <command><return> or <enter>. This will run the hAWK program immediately, without any setup dialog to go through. Hey, that's the whole point..... First let's build hAWK command lines. This is the format of a hAWK command line (note it can cover several lines): ____ hAWK -f"Program Name" -f"Library Name" -s -ss -n -vVariableName="some value" -- MFS "InputFullPathname" ____ and this is what that means: • the command line text must begin with "hAWK" followed by a space or tab • there must be one program name, as signalled by -f. If you just supply a simple program name, it must reside in the "hAWK programs" folder. Use a full path name if the program is in some other folder. If the program name (or any part of the full path name) contains a space, then put quotes "" around the full name, otherwise the quotes are not needed. • the library names are the same as program name, and these are optional. Since library names look the same as the program name, the first one seen is taken as the program name. Libraries are scarce as hen's teeth, so forget about them. • variables are signalled by the -v option, eg -vmyName="Ken E" or -vLevel=1 where the quotes "" are optional if the value contains no spaces or tabs. Spaces before the '=' sign are optional, but don't put any between the '=' and the actual value. Variables are optional. In particular, any variable settings that have been saved with the program (by using the setup dialog) will automatically be passed along with the command line, and so you should set these variables on the command line only if you want to override the default saved values (to see those, select the program in the setup dialog and click the "Set variables..." button). • "--" signals that input files only follow. This is optional, mainly to make reading easier. • "MFS" stands for "all files currently selected for multi-file operations", in other words the bulleted files in your project window as you're no doubt tired of hearing. This one is optional. • input file names are optional, and should be provided as full path names. If any part of the full name contains a space then the quotes "" are necessary, otherwise they're optional. You may also optionally use the following output options (ugh was that English?) in the command line (place them before any "--"): • -s means show stdout when done • -ss means show and select stdout when done • -n means no showing of stdout when done. If you don't provide an output option, any output option from the settings saved with the program will be used instead (these correspond to the "Show/select stdout" checkboxes in the setup dialog). Any output option you do provide overrides the saved settings. You may supply both "MFS" and one or more specific input files on a command line, and unlike the dialog approach you may supply any number of variables (the dialog is limited to 10). Here are some example command lines: ____ hAWK -f$EchoFullPathNames -- MFS hAWK -f$BoilerPlate -vputInComment=1 -vfile="@.c" -vauthor="KE" -vcompany="bdibdi" -ss hAWK -f$FormatFunctionIntro hAWK -f"Disk:Folder:$SomeProgram" -- "Disk:Folder2:OneInputFile" "Disk:Folder3:AnotherInputFile" ____ The first three there are real hAWK programs supplied with EnterAct, and if you take a look at the programs themselves it will help you see what happens with each command line. The last one is made up. "bdibdi" is pronounced "two little bdi's". Now the point of this, as mentioned, is to bypass the setup dialog and call a hAWK program with just a few keystrokes. Since command lines are more than a few keys long, there are two approaches you can take to avoid retyping them: • save them all in a file, and then select them when needed • create a code template with a nice mnemonic name for each command line. This is the handiest approach, provided you don't have several dozen programs you want to run regularly. Code templates are explained in the "Code templates" section of the "Editing" chapter, in fact they're nicely explained at the top of the "EnterAct Code Templates" file which is where they all live. This is essentially a glossary capability, and to use an entry you type its name and press <command><return> to expand it. Code templates know about hAWK templates, and if an entry expands to a hAWK template then it will be selected for you. To run the template, you press <command><return> a second time. Here's a typical code template for a hAWK command line, taken from the EnterAct Code Templates file: ____ ENTRY echo hAWK -f$EchoFullPathNames -- MFS END ____ This means you can get a list of full path names for bulleted files in your project by typing "echo" and then pressing <command><return> twice. The first <command><return> replaces "echo" with the command line, and selects it: the second <command><return> runs the hAWK program "$EchoFullPathNames". To try one out for yourself, open up the EnterAct Code Templates file, scroll down just a little bit to the "boiler" entry, and change the values of the "author" and "company" variables to suit your taste. Save the Templates file, and then (immediately) in any text window type "boiler" and press <command><return> twice. See what you get. Not that tough after all. - - - - - - - - - - - - - - - - Appendix 4 EnterAct as THINK's editor - - - - - - - - - - - - - - - - EnterAct can be used as a replacement for THINK’s own internal editor. This means you can take full advantage of EnterAct’s features when creating your documentation and source, and the THINK Project Manager will be able to track all the changes you make as though you were using its own editor. § Requirements To use EnterAct as a replacement for THINK’s own internal editor, you must have: • EnterAct 2.5 or later (you do) • THINK C 6 or later • System 7 • about 2 Megabytes each for the THINK Project Manager and EnterAct. § Installing EnterAct as THINK’s editor Create an alias of EnterAct, rename it “Editor”, and drop it into the “Tools” or “(Tools)” folder inside your THINK C folder. Then start up THINK Project Manager, and under the Project Managers’s Editor options select “use external editor”—you’ll find this under the Edit menu, in the “Editor” options for the Project Manager. Recommended, deselect the “Reopen files” option in THINK’s Editor options at this point, since EnterAct does a more thorough job of reopening EnterAct project files, and this should prove to be all you need. § Starting a session Start the THINK Project Manager and open a THINK project in your usual way. The first action you undertake that requires viewing a text file will trigger THINK to start EnterAct. Most often you’ll double-click on a file listed in your THINK project, but you might also select the “Open” command, or double-click on the result of a batch find to view a particular instance, etc. In all cases, when EnterAct starts up you will be offered the opportunity to open an existing EnterAct project or create a new one. After you’ve opened or created a project, or cancelled, the text file will open in EnterAct. § Working with EnterAct as THINK’s editor EnterAct and THINK projects serve different purposes, and typically even hold different lists of files—an EnterAct project, for example, can contain source files that are included for reference only, and system and other header files can be explicitly listed in the project window, and your dictionary updated for them, right from the moment you create the project. So you’ll need an EnterAct project to handle your code creation, documentation, and review, and a THINK project to handle compiling and testing. For the most part, when you want to compile or test you should be in THINK, and when you want to edit or view files you should be in EnterAct. To switch from EnterAct to THINK, click in your THINK project window. To return to EnterAct, click in your EnterAct project window, or any open text window that belongs to EnterAct. Though EnterAct may be more tightly coupled to THINK in future versions, this simple approach has the advantage that all of the THINK commands you use regularly are still where you expect under your THINK menus, with one extra click on your THINK project window required to place you back in the right context for them. Of course, opening any text file when in THINK will automatically switch you over to EnterAct in order to display the file. And if a file is listed in both your THINK and EnterAct projects, you can double-click on either instance to open the file, with the same results If all of your changes to source files have been made with EnterAct acting as THINK’s replacement editor, or with THINK’s own editor, then you can bring your THINK project fully up to date with the “Bring Up To Date” command under THINK’s “Project” menu, and there is no need to “Make” or “Scan Disk” to detect which files have changed. Your EnterAct projects will typically need to be brought up to date only for significant changes made outside of function bodies, and if all changes were made with EnterAct you can use the Update Dictionary command under EnterAct’s “EnterAct” menu. Please note that both EnterAct and the THINK Project Manager will automatically note changed files only for the project that is currently open, and if some other project includes a changed file then you will need to use THINK’s “Make” command or EnterAct’s Update Dictionary to bring the project fully up to date. In brief: there is nothing special you need to do when using EnterAct as THINK’s editor. § Using THINK’s Find commands from EnterAct Three commands at the bottom of EnterAct’s Search menu allow you to invoke THINK’s Find commands: specifically, you can view the next or previous matches from a batch find, or call THINK’s “Find In Next File” command from EnterAct. THINK Find Again and THINK Find Previous refer to the results of a batch find done in THINK, and allow you to step through the matches, viewing them with EnterAct. The batch find must first be carried out in THINK, for which see your THINK User Manual. THINK Find In Next File is the equivalent of returning to the THINK Project Manager and selecting “Find In Next File”—once again, you will need to use THINK’s Find dialog to set up the multi-file search beforehand. By the way, EnterAct’s own multi-file searching capabilities are entirely independent of the THINK Project Manager’s. To do a straight multi-file search, you should use EnterAct, since here it is slightly easier to set up. For a batch find, you’ll need to set your search up in the THINK Project Manager and then use THINK Find Again and THINK Find Previous in EnterAct afterwards. (EnterAct also has a batch find, but doesn't (yet) have the nifty Find Previous gizmoid. To jump to a particular instance of one of EnterAct's finds, click on the line reporting the find and use "Go to...".) Find in THINK Reference does the same thing as the command of the same name in the THINK Project Manager's editor: it passes your currently-selected text over to THINK Reference, where you'll be shown any entry it has on the name in question. Note this works only with THINK Reference version 2 or later. For this command to work, you need to have a folder named "Tools" or "(Tools)" next to EnterAct, and drop an alias of THINK Reference in it. - - - - - - - - - - - - - - - - Appendix 5 EnterAct and Code Warrior - - - - - - - - - - - - - - - - By default, when you open a document and Code Warrior also has the document open, EnterAct will put up a dialog giving you the options of forcing Code Warrior to save and close the file before EnterAct opens it, or of cancelling the Open. If you're not sure, return to Code Warrior and decide whether or not to save the file. Note if you do click "OK" to have EnterAct tell Code Warrior to save and close the file, any changes to the file will not be undoable --after all, it's not like editors these days have 10,000-level persistent selective undo or anything. But shouldn't they? As described elsewhere, EnterAct will by default save all documents when you switch out, and refresh them from disk when you switch back (only if needed of course). So there is no decision to make when editing documents with Code Warrior while EnterAct has the same documents open, since EnterAct will have already saved them. When you switch back to EnterAct, if you left the document open with Code Warrior you'll get that dialog asking about forcing Code Warrior to save and close it, or if you saved and closed the document before leaving Code Warrior then EnterAct will just refresh the document from disk. The "default" referred to above is the “Safe switching...” option in EnterAct's Options dialog, which is on by default and saves your documents when you switch out from EnterAct. Better to save too often, since you can always revert with the “Show Activities” command and a little cut and paste. To use EnterAct as just a looker-upper with Code Warrior, see "§ EnterAct as a "definition finder" for other editors" in the Lookup chapter. You can use EnterAct's multi-file search independently of Code Warrior's, and EnterAct's is often handier because you can include more files in your EnterAct project (all toolbox headers, or files from several separate Code Warrior projects, or all Power Plant files, for example). - - - - - - - - - - - - - - - - Appendix 6 the Scripts menu - - - - - - - - - - - - - - - - EnterAct itself understands only the four basic Apple events, but you can use it to run any compiled AppleScript: just drop the script in your "(EnterAct Scripts)" folder and it will appear under EnterAct's Scripts menu (the next time you start EnterAct). The scripts must be compiled, and should be the sort that don't need any parameters or events to get going, and that quit when they're done their specific task. Recompiling your current CW or Symantec project is an example. Any text your script puts in the AppleScript "result" variable will be shown to you when the script terminates, in EnterAct's stdout window. To see it work, try the "Beep Once" script that's supplied. You should see the stdout window after you hear a beep. Event handling is minimal in EnterAct while a script is running: you can interrupt a script with <Command><period>, and switch out of EnterAct, but nothing else. The upshot is that scripts are appropriate for running within EnterAct if they do something not too lengthy that has to be done anyway before you can continue. Scripts that are to run all the time or that take a very long time should be run some other way (eg by double-clicking on the script itself).